@happyvertical/smrt-messages 0.60.8 → 0.60.10

package/dist/smrt-knowledge.json

@@ -3,13 +3,14 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-messages",
-  "packageVersion": "0.60.8",
+  "packageVersion": "0.60.10",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "21c08cb3dacc79e9435b5009bdeb3d2ee3f55684e174ba36e1f85918b203f0a1",
-    "packageJson": "96e94e884580caaab16b5229387e52cdb6644dc207a2160409a61597319ee907",
-    "agents": "75703e49b75d6a74d5f018e8700344a59a970a85f55ee1a5d443f3e99eaca96d"
+    "manifest": "a997261a79d14f9861d9e7960f327718b4f53fe5d605bc79ec9813b59191c686",
+    "packageJson": "5ea3a0c6c3f70caa37499d8ce65a3dd662dbff84c22e012042311d2443dd08b6",
+    "agents": "8a288e588d8fe22e11912ff3e786e65c92bde9f69df6476f2be3b8eb7058528f",
+    "moduleDoc:agents/notification-outbox.md": "c52c52bc6e86da5520982f79ec46f47a926fa8dc1a12e44f4e6bbb5b1fdbd4e3"
   },
   "exports": [
     ".",
@@ -79,7 +80,7 @@
     "typescript"
   ],
   "risks": [
-    "cross-package-refs:7",
+    "cross-package-refs:8",
     "sensitive-fields-excluded",
     "sti-inheritance"
   ],
@@ -2805,6 +2806,23 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "NotificationDeliveryCollection",
+      "qualifiedName": "@happyvertical/smrt-messages:NotificationDeliveryCollection",
+      "collection": "notificationdeliveries",
+      "tableName": "notification_deliveries",
+      "packageName": "@happyvertical/smrt-messages",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "PersonaMessageRouteCollection",
       "qualifiedName": "@happyvertical/smrt-messages:PersonaMessageRouteCollection",
@@ -4123,6 +4141,7 @@
         }
       ],
       "methods": [
+        "abandonSendAttempt",
         "createForward",
         "createReply",
         "getAccount",
@@ -4140,6 +4159,7 @@
         "getThreadEmails",
         "getThreadMessages",
         "getToAddresses",
+        "isSendOutcomeUnknown",
         "isUnread",
         "markRead",
         "markUnread",
@@ -4153,6 +4173,14 @@
         "toggleFlagged"
       ],
       "methodSignatures": [
+        {
+          "name": "abandonSendAttempt",
+          "async": true,
+          "params": [
+            "reason: string"
+          ],
+          "returns": "Promise<boolean>"
+        },
         {
           "name": "createForward",
           "returns": "Email"
@@ -4233,6 +4261,10 @@
           "name": "getToAddresses",
           "returns": "Array<object>"
         },
+        {
+          "name": "isSendOutcomeUnknown",
+          "returns": "boolean"
+        },
         {
           "name": "isUnread",
           "returns": "boolean"
@@ -4460,6 +4492,18 @@
           "operation": "send",
           "objectName": "@happyvertical/smrt-messages:Email"
         },
+        {
+          "kind": "cli",
+          "name": "email_isSendOutcomeUnknown",
+          "operation": "isSendOutcomeUnknown",
+          "objectName": "@happyvertical/smrt-messages:Email"
+        },
+        {
+          "kind": "cli",
+          "name": "email_abandonSendAttempt",
+          "operation": "abandonSendAttempt",
+          "objectName": "@happyvertical/smrt-messages:Email"
+        },
         {
           "kind": "cli",
           "name": "email_retrySend",
@@ -4558,6 +4602,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "abandonSendAttempt",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-messages:Email"
+        },
         {
           "kind": "api",
           "operation": "createForward",
@@ -4677,6 +4728,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-messages:Email"
         },
+        {
+          "kind": "api",
+          "operation": "isSendOutcomeUnknown",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-messages:Email"
+        },
         {
           "kind": "api",
           "operation": "isUnread",
@@ -6090,6 +6148,7 @@
         }
       ],
       "methods": [
+        "abandonSendAttempt",
         "createForward",
         "createReply",
         "getAccount",
@@ -6099,6 +6158,7 @@
         "getPreview",
         "getThreadMessages",
         "getToAddresses",
+        "isSendOutcomeUnknown",
         "isUnread",
         "markRead",
         "markUnread",
@@ -6109,6 +6169,14 @@
         "toggleFlagged"
       ],
       "methodSignatures": [
+        {
+          "name": "abandonSendAttempt",
+          "async": true,
+          "params": [
+            "reason: string"
+          ],
+          "returns": "Promise<boolean>"
+        },
         {
           "name": "createForward",
           "returns": "Message"
@@ -6155,6 +6223,10 @@
           "name": "getToAddresses",
           "returns": "Array<object>"
         },
+        {
+          "name": "isSendOutcomeUnknown",
+          "returns": "boolean"
+        },
         {
           "name": "isUnread",
           "returns": "boolean"
@@ -6348,6 +6420,18 @@
           "operation": "send",
           "objectName": "@happyvertical/smrt-messages:Message"
         },
+        {
+          "kind": "cli",
+          "name": "message_isSendOutcomeUnknown",
+          "operation": "isSendOutcomeUnknown",
+          "objectName": "@happyvertical/smrt-messages:Message"
+        },
+        {
+          "kind": "cli",
+          "name": "message_abandonSendAttempt",
+          "operation": "abandonSendAttempt",
+          "objectName": "@happyvertical/smrt-messages:Message"
+        },
         {
           "kind": "cli",
           "name": "message_retrySend",
@@ -6380,6 +6464,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "abandonSendAttempt",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-messages:Message"
+        },
         {
           "kind": "api",
           "operation": "createForward",
@@ -6443,6 +6534,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-messages:Message"
         },
+        {
+          "kind": "api",
+          "operation": "isSendOutcomeUnknown",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-messages:Message"
+        },
         {
           "kind": "api",
           "operation": "isUnread",
@@ -6682,6 +6780,234 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "NotificationDelivery",
+      "qualifiedName": "@happyvertical/smrt-messages:NotificationDelivery",
+      "collection": "notificationdeliveries",
+      "description": "One durable, source-keyed notification delivery to one person over one external channel (the outbox row behind NotificationOutboxService).",
+      "tableName": "notification_deliveries",
+      "packageName": "@happyvertical/smrt-messages",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "recipientUserId",
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        },
+        {
+          "name": "channel",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "default": "email"
+        },
+        {
+          "name": "sourceRef",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "kind",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "subject",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "textBody",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "href",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "recipientAddress",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "recipientName",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "accountId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Account",
+          "columnType": "UUID"
+        },
+        {
+          "name": "messageId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Message",
+          "columnType": "UUID"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "pending"
+        },
+        {
+          "name": "stateVersion",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "transitionId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "attempts",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "maxAttempts",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 5
+        },
+        {
+          "name": "nextAttemptAt",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "leaseToken",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "leaseExpiresAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "handedOffAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "deliveredAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "providerMessageId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "lastError",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "recipientUserId",
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        },
+        {
+          "name": "accountId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Account",
+          "columnType": "UUID"
+        },
+        {
+          "name": "messageId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Message",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "transition"
+      ],
+      "methodSignatures": [
+        {
+          "name": "transition",
+          "async": true,
+          "params": [
+            "changes: NotificationDeliveryTransition",
+            "expected?: object"
+          ],
+          "returns": "Promise<boolean>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "recipient_user_id",
+        "channel",
+        "source_ref"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "transition",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-messages:NotificationDelivery"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "PersonaMessageRoute",
       "qualifiedName": "@happyvertical/smrt-messages:PersonaMessageRoute",
@@ -7422,6 +7748,7 @@
         }
       ],
       "methods": [
+        "abandonSendAttempt",
         "createForward",
         "createReply",
         "getAccount",
@@ -7435,6 +7762,7 @@
         "getToAddresses",
         "getTotalReactions",
         "isInThread",
+        "isSendOutcomeUnknown",
         "isUnread",
         "markRead",
         "markUnread",
@@ -7445,6 +7773,14 @@
         "toggleFlagged"
       ],
       "methodSignatures": [
+        {
+          "name": "abandonSendAttempt",
+          "async": true,
+          "params": [
+            "reason: string"
+          ],
+          "returns": "Promise<boolean>"
+        },
         {
           "name": "createForward",
           "returns": "Message"
@@ -7507,6 +7843,10 @@
           "name": "isInThread",
           "returns": "boolean"
         },
+        {
+          "name": "isSendOutcomeUnknown",
+          "returns": "boolean"
+        },
         {
           "name": "isUnread",
           "returns": "boolean"
@@ -7697,6 +8037,18 @@
           "operation": "send",
           "objectName": "@happyvertical/smrt-messages:SlackMessage"
         },
+        {
+          "kind": "cli",
+          "name": "slackmessage_isSendOutcomeUnknown",
+          "operation": "isSendOutcomeUnknown",
+          "objectName": "@happyvertical/smrt-messages:SlackMessage"
+        },
+        {
+          "kind": "cli",
+          "name": "slackmessage_abandonSendAttempt",
+          "operation": "abandonSendAttempt",
+          "objectName": "@happyvertical/smrt-messages:SlackMessage"
+        },
         {
           "kind": "cli",
           "name": "slackmessage_retrySend",
@@ -7753,6 +8105,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "abandonSendAttempt",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-messages:SlackMessage"
+        },
         {
           "kind": "api",
           "operation": "createForward",
@@ -7844,6 +8203,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-messages:SlackMessage"
         },
+        {
+          "kind": "api",
+          "operation": "isSendOutcomeUnknown",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-messages:SlackMessage"
+        },
         {
           "kind": "api",
           "operation": "isUnread",
@@ -8476,6 +8842,7 @@
         }
       ],
       "methods": [
+        "abandonSendAttempt",
         "createForward",
         "createReply",
         "getAccount",
@@ -8489,6 +8856,7 @@
         "getPreview",
         "getThreadMessages",
         "getToAddresses",
+        "isSendOutcomeUnknown",
         "isUnread",
         "markRead",
         "markUnread",
@@ -8499,6 +8867,14 @@
         "toggleFlagged"
       ],
       "methodSignatures": [
+        {
+          "name": "abandonSendAttempt",
+          "async": true,
+          "params": [
+            "reason: string"
+          ],
+          "returns": "Promise<boolean>"
+        },
         {
           "name": "createForward",
           "returns": "Message"
@@ -8561,6 +8937,10 @@
           "name": "getToAddresses",
           "returns": "Array<object>"
         },
+        {
+          "name": "isSendOutcomeUnknown",
+          "returns": "boolean"
+        },
         {
           "name": "isUnread",
           "returns": "boolean"
@@ -8751,6 +9131,18 @@
           "operation": "send",
           "objectName": "@happyvertical/smrt-messages:Tweet"
         },
+        {
+          "kind": "cli",
+          "name": "tweet_isSendOutcomeUnknown",
+          "operation": "isSendOutcomeUnknown",
+          "objectName": "@happyvertical/smrt-messages:Tweet"
+        },
+        {
+          "kind": "cli",
+          "name": "tweet_abandonSendAttempt",
+          "operation": "abandonSendAttempt",
+          "objectName": "@happyvertical/smrt-messages:Tweet"
+        },
         {
           "kind": "cli",
           "name": "tweet_retrySend",
@@ -8807,6 +9199,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "abandonSendAttempt",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-messages:Tweet"
+        },
         {
           "kind": "api",
           "operation": "createForward",
@@ -8898,6 +9297,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-messages:Tweet"
         },
+        {
+          "kind": "api",
+          "operation": "isSendOutcomeUnknown",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-messages:Tweet"
+        },
         {
           "kind": "api",
           "operation": "isUnread",
@@ -10871,6 +11277,18 @@
       "operation": "send",
       "objectName": "@happyvertical/smrt-messages:Email"
     },
+    {
+      "kind": "cli",
+      "name": "email_isSendOutcomeUnknown",
+      "operation": "isSendOutcomeUnknown",
+      "objectName": "@happyvertical/smrt-messages:Email"
+    },
+    {
+      "kind": "cli",
+      "name": "email_abandonSendAttempt",
+      "operation": "abandonSendAttempt",
+      "objectName": "@happyvertical/smrt-messages:Email"
+    },
     {
       "kind": "cli",
       "name": "email_retrySend",
@@ -11419,6 +11837,18 @@
       "operation": "send",
       "objectName": "@happyvertical/smrt-messages:Message"
     },
+    {
+      "kind": "cli",
+      "name": "message_isSendOutcomeUnknown",
+      "operation": "isSendOutcomeUnknown",
+      "objectName": "@happyvertical/smrt-messages:Message"
+    },
+    {
+      "kind": "cli",
+      "name": "message_abandonSendAttempt",
+      "operation": "abandonSendAttempt",
+      "objectName": "@happyvertical/smrt-messages:Message"
+    },
     {
       "kind": "cli",
       "name": "message_retrySend",
@@ -11707,6 +12137,18 @@
       "operation": "send",
       "objectName": "@happyvertical/smrt-messages:SlackMessage"
     },
+    {
+      "kind": "cli",
+      "name": "slackmessage_isSendOutcomeUnknown",
+      "operation": "isSendOutcomeUnknown",
+      "objectName": "@happyvertical/smrt-messages:SlackMessage"
+    },
+    {
+      "kind": "cli",
+      "name": "slackmessage_abandonSendAttempt",
+      "operation": "abandonSendAttempt",
+      "objectName": "@happyvertical/smrt-messages:SlackMessage"
+    },
     {
       "kind": "cli",
       "name": "slackmessage_retrySend",
@@ -11939,6 +12381,18 @@
       "operation": "send",
       "objectName": "@happyvertical/smrt-messages:Tweet"
     },
+    {
+      "kind": "cli",
+      "name": "tweet_isSendOutcomeUnknown",
+      "operation": "isSendOutcomeUnknown",
+      "objectName": "@happyvertical/smrt-messages:Tweet"
+    },
+    {
+      "kind": "cli",
+      "name": "tweet_abandonSendAttempt",
+      "operation": "abandonSendAttempt",
+      "objectName": "@happyvertical/smrt-messages:Tweet"
+    },
     {
       "kind": "cli",
       "name": "tweet_retrySend",
@@ -12188,14 +12642,21 @@
   ],
   "prompts": [],
   "relationshipsV2": {
-    "foreignKeyFields": 16,
-    "crossPackageRefFields": 7,
+    "foreignKeyFields": 18,
+    "crossPackageRefFields": 8,
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 96
+    "uuidColumns": 106
   },
-  "agentDoc": "# @happyvertical/smrt-messages\n\nMulti-channel messaging with STI hierarchies for both messages and accounts. Credential encryption via smrt-secrets.\n\n## STI Hierarchies\n\n**Messages** (share `messages` table):\n- `Message` (base): accountId, personaId, endpointId, correlationId, threadId, subject, body, fromAddress, toAddresses (JSON), sendStatus (draft/sending/sent/failed), retryCount\n- `Email`: messageId (RFC 822), inReplyTo, ccAddresses, bccAddresses, htmlBody, textBody, folderId, labels, headers\n- `Tweet`: tweetId, retweetCount, likeCount, mediaUrls, hashtags, mentions\n- `SlackMessage`: channelId, slackTs, slackThreadTs, reactions, blocks\n\n**Accounts** (share `accounts` table):\n- `Account` (base): channelType, providerType, public configuration,\n  credentialSecretId, isActive, lastSyncAt, deprecated sensitive settings\n- `EmailAccount`, `TwitterAccount`, `SlackAccount`, `ZulipAccount`,\n  `TelegramAccount`: provider-specific identity/sender behavior\n\n## Persona messaging\n\n- `MessagingEndpoint`: tenant-owned, write-only destination JSON with masked\n  display helper.\n- `PersonaMessageRoute`: persona → account + endpoint, selected by purpose and\n  descending priority.\n- `PersonaMessagingService`: persists and sends through an enabled route.\n- Provider registry: public setup descriptors + optional sender factory. Keep\n  channel (`sms`) separate from provider (`twilio`).\n- Permissions: `messages.send`, `messages.manage-routes`,\n  `messages.manage-credentials`.\n- `MessagingSettingsService` is the permissioned server boundary;\n  its host-supplied `resolvePersonaTenantId` proves cross-package ownership.\n  `MessagingSettingsPanel` is the callback-driven Svelte surface.\n- Account, endpoint, and route generated surfaces are read-only. Do not add\n  generated mutations around the settings service or make secret fields writable.\n- **Recipe `messages.slack`** (`src/recipes.ts`, help in `src/help/slack.md`): lists Slack messages and workspaces beside the Mailbox and Notifications recipes; workspaces stay read-only and sending goes through the senders, not generated routes. Fields it shows carry `@field({ description })` in plain words; keep them when editing the models.\n\n## In-app notifications (`UserNotification`)\n\nThe in-app channel: one stored row per person, with read state.\n`user_notifications`: `tenantId` (required), `recipientUserId`\n(`@crossPackageRef` smrt-users:User, uuid), `kind`, `title`, `body`, `href`,\n`severity` (info/success/warning/error), `sourceRef`, `occurredAt`, `readAt`,\n`dismissedAt`. Conflict identity `(tenant_id, recipient_user_id, source_ref)`.\n\n- `UserNotificationService` is the only access path: `notify()` /\n  `notifyMany()` (dedupe on `sourceRef`, existing row returned untouched;\n  a unique ref is generated when omitted), `listForUser()` / `countUnread()`\n  across explicit `tenantIds` (each read under `withTenant`), `markRead()`,\n  `dismiss()` (also marks read), `markAllRead()`. Every write filters on the\n  recipient, so another user's id matches nothing.\n- Generated REST/MCP/CLI are off (`api`/`mcp`/`cli: false`): a tenant-scoped\n  list would expose every member's rows. Hosts expose their own routes that\n  pass the signed-in user's id, never a request-chosen one.\n- Hosts decide who is told (e.g. `SocialPost.createdByUserId` for a failed\n  post). New table: consumers run `db:migrate`.\n\n## Credential Security\n\nAccount credentials stored via tenant-bound `credentialSecretId` →\nsmrt-secrets. Use `setCredentials()`/`getCredentials()` — never store passwords\ndirectly. Credential descriptor schemas contain field definitions, never values.\n\n## Send Lifecycle\n\n`message.send()`: resolves account → creates provider sender → updates sendStatus. Retry support with `maxRetries` budget.\n`EmailSender` attaches the message's stored `Attachment` rows (read through\n`Attachment.readContent()`, under the message's tenant context) plus\n`SendEmailOptions.attachments` bytes; an unreadable or file-less row fails the\nsend with the error on `sendError`, never a silent drop (#3808).\n`PersonaMessagingService.send({ attachments })` accepts them on email routes only.\n\n## Provider entry points (bundle boundary, #1979)\n\nThe package root is provider-neutral: models, collections, services,\npermissions, and the provider registry carry **zero provider-SDK weight**.\nProvider SDK wrappers (`@happyvertical/email`, `@happyvertical/messages`) are\nreachable only through explicit entry points, imported once at server startup:\n\n```ts\nimport '@happyvertical/smrt-messages/providers/email';   // smtp/imap/pop3/gmail\nimport '@happyvertical/smrt-messages/providers/slack';\nimport '@happyvertical/smrt-messages/providers/twitter';\nimport '@happyvertical/smrt-messages/providers/all';     // all of the above\n```\n\n- Without the matching entry, `EmailAccount.createClient()` (send + mailbox\n  sync) throws an actionable error and `SlackSender`/`TweetSender` return a\n  failure result naming the entry to import. Telegram and Zulip are\n  fetch-based and always work from the root.\n- Builtin registry definitions stay metadata-only (setup fields for UIs); the\n  entries upgrade them with `createEmailClient`/`createMessageClient`/\n  `createSender` hooks. Never import a provider SDK from any module reachable\n  from `src/index.ts` — the consumer bundle gate (`packages/bundle-gate`)\n  fails CI when one becomes reachable.\n- `Attachment.readContent()` loads `@happyvertical/files` through core's\n  `importOptionalDependency` boundary and keeps its null-on-failure contract\n  in builds where the SDK is absent.\n\n## Gotchas\n\n- **Manifest before decorators**: every decorated model imports\n  `../__smrt-register__.js`, and `package.json#sideEffects` lists\n  `./src/__smrt-register__.ts`. Without both, the library build dropped or\n  reordered the self-registration, so dist classes registered with only their\n  decorated fields and could adopt smrt-ledgers' same-named `Account` (#3098).\n- **`Account` is not unique**: smrt-ledgers also declares `Account` (on\n  `ledger_accounts`). Resolve by constructor or qualified name; the\n  coexistence tests (`ledger-account-identity-*`, and the PostgreSQL lane\n  `pnpm test:postgres`) load both packages in both orders.\n- **STI `_meta_type`**: qualified format `@happyvertical/smrt-messages:Email`\n- **JSON fields**: all address/metadata fields are JSON strings with `getX()`/`setX()` helpers\n- **RFC 822 threading**: Email uses `inReplyTo`/`messageId`/`references` — manual management required\n- **Attachment.messageId**: use this field (not `emailId`); old getter/setter mapped via deprecation wrapper\n- **Optional tenancy**: `@TenantScoped({ mode: 'optional' })` on Message, Account, Attachment\n- **Required tenancy**: endpoints and persona routes are always tenant scoped\n- **Secrets are write-only**: never serialize credentials or endpoint.address to an app\n\n## Intake byte snapshots\n\n`EmailAccount.readIntakeMessage(providerLookup, maxBytes, imapIdentity?)` is the authorized host seam for\nopt-in ingestion. It copies full-message attachment bytes from the registered\nemail provider and fails when only attachment metadata is available; it never\nreads provider-supplied paths or advances sync checkpoints. Keep this path\nprovider-neutral and exclude arbitrary headers/credentials from its snapshot.\nIMAP lookup must include folder/UIDVALIDITY/UID verification; sender Message-ID\nis a lookup hint, never the durable delivery identity.\n",
+  "agentDoc": "# @happyvertical/smrt-messages\n\nMulti-channel messaging with STI hierarchies for both messages and accounts. Credential encryption via smrt-secrets.\n\n## STI Hierarchies\n\n**Messages** (share `messages` table):\n- `Message` (base): accountId, personaId, endpointId, correlationId, threadId, subject, body, fromAddress, toAddresses (JSON), sendStatus (draft/sending/sent/failed), retryCount\n- `Email`: messageId (RFC 822), inReplyTo, ccAddresses, bccAddresses, htmlBody, textBody, folderId, labels, headers\n- `Tweet`: tweetId, retweetCount, likeCount, mediaUrls, hashtags, mentions\n- `SlackMessage`: channelId, slackTs, slackThreadTs, reactions, blocks\n\n**Accounts** (share `accounts` table):\n- `Account` (base): channelType, providerType, public configuration,\n  credentialSecretId, isActive, lastSyncAt, deprecated sensitive settings\n- `EmailAccount`, `TwitterAccount`, `SlackAccount`, `ZulipAccount`,\n  `TelegramAccount`: provider-specific identity/sender behavior\n\n## Persona messaging\n\n- `MessagingEndpoint`: tenant-owned, write-only destination JSON with masked\n  display helper.\n- `PersonaMessageRoute`: persona → account + endpoint, selected by purpose and\n  descending priority.\n- `PersonaMessagingService`: persists and sends through an enabled route.\n- Provider registry: public setup descriptors + optional sender factory. Keep\n  channel (`sms`) separate from provider (`twilio`).\n- Permissions: `messages.send`, `messages.manage-routes`,\n  `messages.manage-credentials`.\n- `MessagingSettingsService` is the permissioned server boundary;\n  its host-supplied `resolvePersonaTenantId` proves cross-package ownership.\n  `MessagingSettingsPanel` is the callback-driven Svelte surface.\n- Account, endpoint, and route generated surfaces are read-only. Do not add\n  generated mutations around the settings service or make secret fields writable.\n- **Recipe `messages.slack`** (`src/recipes.ts`, help in `src/help/slack.md`): lists Slack messages and workspaces beside the Mailbox and Notifications recipes; workspaces stay read-only and sending goes through the senders, not generated routes. Fields it shows carry `@field({ description })` in plain words; keep them when editing the models.\n\n## In-app notifications (`UserNotification`)\n\nThe in-app channel: one stored row per person, with read state.\n`user_notifications`: `tenantId` (required), `recipientUserId`\n(`@crossPackageRef` smrt-users:User, uuid), `kind`, `title`, `body`, `href`,\n`severity` (info/success/warning/error), `sourceRef`, `occurredAt`, `readAt`,\n`dismissedAt`. Conflict identity `(tenant_id, recipient_user_id, source_ref)`.\n\n- `UserNotificationService` is the only access path: `notify()` /\n  `notifyMany()` (dedupe on `sourceRef`, existing row returned untouched;\n  a unique ref is generated when omitted), `listForUser()` / `countUnread()`\n  across explicit `tenantIds` (each read under `withTenant`), `markRead()`,\n  `dismiss()` (also marks read), `markAllRead()`. Every write filters on the\n  recipient, so another user's id matches nothing.\n- Generated REST/MCP/CLI are off (`api`/`mcp`/`cli: false`): a tenant-scoped\n  list would expose every member's rows. Hosts expose their own routes that\n  pass the signed-in user's id, never a request-chosen one.\n- Hosts decide who is told (e.g. `SocialPost.createdByUserId` for a failed\n  post). New table: consumers run `db:migrate`.\n\n## Notification email outbox (`NotificationDelivery`)\n\n`NotificationOutboxService` is the external-channel counterpart of\n`UserNotificationService`: `enqueueEmail()` stores one delivery per\n`(tenant, recipient, channel, sourceRef)` after the host resolves the\nrecipient address and same-tenant sender account (callers never choose an\naddress); `dispatchDue()` leases due rows by compare-and-set\n(`NotificationDelivery.transition()`), creates the single outbound `Email`\nunder the lease, and settles sent/retry/failed/uncertain. Never resend an\n`uncertain` row automatically. Contract, retry, and reconciliation policy:\n[agents/notification-outbox.md](agents/notification-outbox.md). New table:\nconsumers run `db:migrate`.\n\n## Credential Security\n\nAccount credentials stored via tenant-bound `credentialSecretId` →\nsmrt-secrets. Use `setCredentials()`/`getCredentials()` — never store passwords\ndirectly. Credential descriptor schemas contain field definitions, never values.\n\n## Send Lifecycle\n\n`message.send()`: resolves account → creates provider sender → updates sendStatus. Retry support with `maxRetries` budget.\nA failure the provider may still have accepted carries\n`MessageSendResult.outcomeUnknown` (set by `EmailSender` unless\n`isDefiniteSendRejection()` proves a refusal, and when a sender throws) and is\npersisted as `metadata.sendOutcomeUnknown`; never auto-resend it.\n`EmailSender` attaches the message's stored `Attachment` rows (read through\n`Attachment.readContent()`, under the message's tenant context) plus\n`SendEmailOptions.attachments` bytes; an unreadable or file-less row fails the\nsend with the error on `sendError`, never a silent drop (#3808).\n`PersonaMessagingService.send({ attachments })` accepts them on email routes only.\n\n## Provider entry points (bundle boundary, #1979)\n\nThe package root is provider-neutral: models, collections, services,\npermissions, and the provider registry carry **zero provider-SDK weight**.\nProvider SDK wrappers (`@happyvertical/email`, `@happyvertical/messages`) are\nreachable only through explicit entry points, imported once at server startup:\n\n```ts\nimport '@happyvertical/smrt-messages/providers/email';   // smtp/imap/pop3/gmail\nimport '@happyvertical/smrt-messages/providers/slack';\nimport '@happyvertical/smrt-messages/providers/twitter';\nimport '@happyvertical/smrt-messages/providers/all';     // all of the above\n```\n\n- Without the matching entry, `EmailAccount.createClient()` (send + mailbox\n  sync) throws an actionable error and `SlackSender`/`TweetSender` return a\n  failure result naming the entry to import. Telegram and Zulip are\n  fetch-based and always work from the root.\n- Builtin registry definitions stay metadata-only (setup fields for UIs); the\n  entries upgrade them with `createEmailClient`/`createMessageClient`/\n  `createSender` hooks. Never import a provider SDK from any module reachable\n  from `src/index.ts` — the consumer bundle gate (`packages/bundle-gate`)\n  fails CI when one becomes reachable.\n- `Attachment.readContent()` loads `@happyvertical/files` through core's\n  `importOptionalDependency` boundary and keeps its null-on-failure contract\n  in builds where the SDK is absent.\n\n## Gotchas\n\n- **Manifest before decorators**: every decorated model imports\n  `../__smrt-register__.js`, and `package.json#sideEffects` lists\n  `./src/__smrt-register__.ts`. Without both, the library build dropped or\n  reordered the self-registration, so dist classes registered with only their\n  decorated fields and could adopt smrt-ledgers' same-named `Account` (#3098).\n- **`Account` is not unique**: smrt-ledgers also declares `Account` (on\n  `ledger_accounts`). Resolve by constructor or qualified name; the\n  coexistence tests (`ledger-account-identity-*`, and the PostgreSQL lane\n  `pnpm test:postgres`) load both packages in both orders.\n- **STI `_meta_type`**: qualified format `@happyvertical/smrt-messages:Email`\n- **JSON fields**: all address/metadata fields are JSON strings with `getX()`/`setX()` helpers\n- **RFC 822 threading**: Email uses `inReplyTo`/`messageId`/`references` — manual management required\n- **Attachment.messageId**: use this field (not `emailId`); old getter/setter mapped via deprecation wrapper\n- **Optional tenancy**: `@TenantScoped({ mode: 'optional' })` on Message, Account, Attachment\n- **Required tenancy**: endpoints and persona routes are always tenant scoped\n- **Secrets are write-only**: never serialize credentials or endpoint.address to an app\n\n## Intake byte snapshots\n\n`EmailAccount.readIntakeMessage(providerLookup, maxBytes, imapIdentity?)` is the authorized host seam for\nopt-in ingestion. It copies full-message attachment bytes from the registered\nemail provider and fails when only attachment metadata is available; it never\nreads provider-supplied paths or advances sync checkpoints. Keep this path\nprovider-neutral and exclude arbitrary headers/credentials from its snapshot.\nIMAP lookup must include folder/UIDVALIDITY/UID verification; sender Message-ID\nis a lookup hint, never the durable delivery identity.\n",
+  "moduleDocs": [
+    {
+      "path": "agents/notification-outbox.md",
+      "module": "notification-outbox",
+      "content": "# Notification email outbox (#4237)\n\n`NotificationOutboxService` turns a host event into at most one outbound email\nper recipient and delivers it from a crash-safe, leased outbox. It pairs with\n`UserNotificationService`: hosts that tell someone in-app and by email pass the\nsame `sourceRef` to both.\n\nSource: `src/models/NotificationDelivery.ts`,\n`src/services/NotificationOutboxService.ts`,\ntests `src/__tests__/notification-outbox*.test.ts`.\n\n## Enqueue\n\n`enqueueEmail({ tenantId, recipientUserId, sourceRef, kind, subject, text, path, notBefore? })`\nstores one `NotificationDelivery` (`notification_deliveries`) per\n`(tenant_id, recipient_user_id, channel, source_ref)`, the conflict identity. A\nrepeat (or a concurrent duplicate that loses the insert) returns the stored row\nuntouched with `created: false`. Encode each distinct event in `sourceRef`, e.g.\n`project-question:<id>:asked` and `project-question:<id>:reminder:<n>`.\n\nHost authorization, all checked before anything is stored:\n\n- `resolveRecipient({ tenantId, recipientUserId, channel })` returns the address\n  the host allows for that user in that tenant, or `null` (denied with\n  `NotificationOutboxDeniedError`, reason `recipient`). Callers never pass an\n  address; the resolved one is snapshotted on the row.\n- `resolveSenderAccountId({ tenantId })` names an active `EmailAccount` owned by\n  the same tenant (reason `sender` otherwise). Configuring that account is\n  deployment setup; the outbox has no mail transport of its own.\n- With `principal`, enqueue, `listUncertain`, and `reconcile` require\n  `messages.send` in the tenant (reason `permission`). Omit it only for trusted\n  system code that authorizes itself.\n- `isSuppressed(...)` (optional) is the opt-out hook. A suppressed enqueue stores\n  a `cancelled` row (so the event stays deduplicated); suppression at dispatch\n  cancels before handoff. The package has no preference store of its own.\n\nDeep links: `path` must be host-relative (`/portal/...`); it is joined to\n`linkBaseUrl` (absolute http(s), no credentials/query/fragment, validated at\nconstruction) and must stay on that origin — `//host`, backslashes, whitespace,\nand control characters are refused (reason `link`). The link is stored on the\nrow, so a duplicate enqueue keeps the first link. Links carry no tokens: they\nlead to the host's normal authenticated route. Subjects must be one line.\n\n## Dispatch\n\n`dispatchDue({ tenantIds?, limit? })` (default 25, max 200) leases due rows —\n`pending` with `nextAttemptAt <= now`, and `sending` rows whose lease lapsed —\nfor the given tenants, or every tenant (discovered under `withSystemContext`)\nwhen `tenantIds` is omitted. Each row is processed under `withTenant(row.tenantId)`.\nRun it from a scheduled job; several workers may run it concurrently.\n\nEvery state change is `NotificationDelivery.transition()`: a compare-and-set on\n`stateVersion` (and the lease token for a lease holder) that writes a unique\n`transitionId` and re-reads the row to prove the write won. PostgreSQL and\nremote LibSQL use one conditional `UPDATE`; local embedded engines use the\nprocess write queue, like `Message.send()`'s claim.\n\nPer row:\n\n1. Acquire: `status = sending`, new `leaseToken`, `leaseExpiresAt = now + leaseMs`\n   (default 5 min; must exceed the slowest provider call), `attempts + 1`.\n2. Create the single outbound `Email` and record `messageId`. Its id is\n   `notificationDeliveryMessageId(deliveryId)` (a name-based uuid) and it is\n   inserted insert-only, so a crashed or stale dispatcher finds or collides\n   with the stored row instead of creating a second email; its correlation id\n   is `notification-delivery:<deliveryId>`.\n3. Record `handedOffAt`, then call `transport.send({ delivery, message, idempotencyKey })`.\n4. Settle with the lease token: `accepted` → `sent`; `rejected` + `retryable`\n   → `pending` after `retryDelayMs(attempts)` (default 1 min · 2ⁿ⁻¹, capped at\n   1 h) until `maxAttempts` (default 5), then `failed`; non-retryable → `failed`;\n   `unknown` (including a thrown send) → `uncertain`. A holder whose lease was\n   taken over gets `lease-lost` and writes nothing.\n\n## Provider idempotency and reconciliation policy\n\nDelivery is at-most-once once a provider may have seen the message.\n\n- A lapsed lease with no `handedOffAt` never reached the provider: it is resent.\n- Ambiguous provider failures are not rejections. `EmailSender` sets\n  `MessageSendResult.outcomeUnknown` unless `isDefiniteSendRejection()` proves\n  the send was refused (an SMTP reply code, an SDK auth/validation error, a\n  send error that accepted no recipient, or a connection that was never made);\n  `Message.send()` sets it when a sender throws. `Message` persists the marker\n  in `metadata.sendOutcomeUnknown` with the `failed` status\n  (`Message.isSendOutcomeUnknown()`), and `messageSendTransport` maps it to\n  `unknown`, so the delivery becomes `uncertain` instead of being retried.\n- A lapsed lease after `handedOffAt` asks `transport.reconcile()`. The default\n  `messageSendTransport` reads the canonical `Message.sendStatus`: `sent` →\n  delivery `sent` (no resend), `failed` → normal retry (or `uncertain` when the\n  failure carries the outcome-unknown marker), `draft`/`pending` → resend,\n  anything else (e.g. still `sending`) → `uncertain`.\n- `uncertain` rows are never resent automatically. Operators list them with\n  `listUncertain({ tenantId })` and settle them with\n  `reconcile({ tenantId, deliveryId, outcome: 'sent' | 'failed' | 'retry', note? })`\n  after checking the provider; `retry` accepts the risk of a duplicate. It\n  first releases a message a dead sender left `sending`\n  (`Message.abandonSendAttempt()`, a compare-and-set to `failed`) so the next\n  lease can send it, and refuses when the message is recorded as `sent`.\n- A transport with `idempotent: true` declares that its provider deduplicates on\n  `idempotencyKey` (stable per delivery); unknown outcomes are then retried\n  instead of parked. SMTP and the current SDK email providers take no key, so\n  `messageSendTransport` is not idempotent.\n\n## Transport seam\n\n`NotificationTransport { name; idempotent?; send(request); reconcile?(request) }`.\nThe default delivers through `Message.send()` → account → registered provider\nsender (import `@happyvertical/smrt-messages/providers/email` at server\nstartup). Tests inject a fake; nothing in the outbox reaches a provider SDK.\n\n## Schema\n\nNew table `notification_deliveries` (tenant-required, generated REST/MCP/CLI\noff): consumers run `db:migrate`. `recipient_user_id` is a cross-package uuid\nref to `smrt-users:User`; `account_id`/`message_id` are FKs to `accounts` and\n`messages`.\n"
+    }
+  ],
   "recipes": [
     {
       "id": "messages.mailbox",