@happyvertical/smrt-messages 0.60.10 → 0.60.11

package/dist/smrt-knowledge.json

@@ -3,14 +3,14 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-messages",
-  "packageVersion": "0.60.10",
+  "packageVersion": "0.60.11",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "a997261a79d14f9861d9e7960f327718b4f53fe5d605bc79ec9813b59191c686",
-    "packageJson": "5ea3a0c6c3f70caa37499d8ce65a3dd662dbff84c22e012042311d2443dd08b6",
-    "agents": "8a288e588d8fe22e11912ff3e786e65c92bde9f69df6476f2be3b8eb7058528f",
-    "moduleDoc:agents/notification-outbox.md": "c52c52bc6e86da5520982f79ec46f47a926fa8dc1a12e44f4e6bbb5b1fdbd4e3"
+    "manifest": "fa496fbecf14dd88cff8c80445d4e21125abf2242b4bae0d1ee093bf2875216b",
+    "packageJson": "47ae1990a3090feb3d7373881e730c091a23273015fde2bea5b12f9c3e53cf4d",
+    "agents": "25944fbc57127569409696f81aa8bac48529378364e4a59f57586b16780281ae",
+    "moduleDoc:agents/notification-outbox.md": "ba0479c05ffafd22be62e20c0fb8c6eb6db9294e95fd6d988ac1e2f47510e98c"
   },
   "exports": [
     ".",
@@ -80,7 +80,7 @@
     "typescript"
   ],
   "risks": [
-    "cross-package-refs:8",
+    "cross-package-refs:9",
     "sensitive-fields-excluded",
     "sti-inheritance"
   ],
@@ -2823,6 +2823,23 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "NotificationOptOutCollection",
+      "qualifiedName": "@happyvertical/smrt-messages:NotificationOptOutCollection",
+      "collection": "notificationoptouts",
+      "tableName": "notification_opt_outs",
+      "packageName": "@happyvertical/smrt-messages",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "PersonaMessageRouteCollection",
       "qualifiedName": "@happyvertical/smrt-messages:PersonaMessageRouteCollection",
@@ -7008,6 +7025,83 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "NotificationOptOut",
+      "qualifiedName": "@happyvertical/smrt-messages:NotificationOptOut",
+      "collection": "notificationoptouts",
+      "description": "One person's opt-out of one notification channel for one scope, in one tenant: the preference store behind the outbox's isSuppressed hook.",
+      "tableName": "notification_opt_outs",
+      "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": "scope",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "optedOutAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "updatedBy",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "recipientUserId",
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "recipient_user_id",
+        "channel",
+        "scope"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "PersonaMessageRoute",
       "qualifiedName": "@happyvertical/smrt-messages:PersonaMessageRoute",
@@ -12643,18 +12737,18 @@
   "prompts": [],
   "relationshipsV2": {
     "foreignKeyFields": 18,
-    "crossPackageRefFields": 8,
+    "crossPackageRefFields": 9,
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 106
+    "uuidColumns": 112
   },
-  "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",
+  "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`NotificationOptOut` (`notification_opt_outs`, tenant-required, generated\nsurfaces off) is the per-recipient opt-out ledger for the outbox's\n`isSuppressed` hook, keyed `(tenant, recipient, channel, scope)` with scope `*`\nor `project:<uuid>`-style keys. `NotificationOptOutService`: idempotent\n`optOut`/`optIn` (with a `principal` only `userId === recipientUserId` may\nchange a row, and only in the principal's own `tenantId`, else\n`NotificationOptOutDeniedError`; no principal = trusted host code), trusted `isOptedOut` (a `*` row matches every scope), `listForRecipient`\n(principal required). `optOutSuppression(service, scopeOf)` builds the\n`isSuppressed` function. Details in the outbox doc; 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.\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"
+      "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's own preference store is the\n  [opt-out ledger](#opt-out-ledger); wire it with `optOutSuppression`.\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## Opt-out ledger\n\n`NotificationOptOut` (`notification_opt_outs`, tenant-required, generated\nREST/MCP/CLI off) records one row per `(tenant_id, recipient_user_id, channel,\nscope)`: `channel` is `email`; `scope` is `*` (all notification email in the\ntenant) or a host key such as `project:<uuid>` (lowercase prefix, `:`, then\n`[A-Za-z0-9._:-]{1,200}`; malformed scopes throw). `optedOutAt` is set while\nopted out and cleared by an opt-in (the row stays as history); `updatedBy` is\nthe person's user id, or `system` for host code. It exists because\n`smrt-preferences` is owner-read only, while suppression runs where the recipient\nis not the caller (a manager enqueues, a worker dispatches).\n\n`NotificationOptOutService({ db })`:\n\n- `optOut({ tenantId, recipientUserId, channel, scope, principal? })` and\n  `optIn(...)` are idempotent. With `principal: { userId, tenantId }` only\n  `principal.userId === recipientUserId` may change the row, and only when\n  `principal.tenantId` equals the request's tenant: a principal never acts in\n  another tenant (`NotificationOptOutDeniedError`, reason `principal` or\n  `tenant`). Without a principal the call is trusted host code that\n  authenticated the recipient itself (e.g. a signed unsubscribe link, or a host\n  route whose member belongs to a child tenant of the delivery tenant).\n- `isOptedOut({ tenantId, recipientUserId, channel, scope })` is the trusted\n  suppression read, under `withTenant`; a `*` row matches every scope.\n- `listForRecipient({ tenantId, recipientUserId, principal })` returns only the\n  recipient's own active opt-outs; any other principal is denied.\n\n```ts\nconst optOuts = new NotificationOptOutService({ db });\nnew NotificationOutboxService({\n  // ...\n  // `scopeOf` maps the host's own event to a scope; null = not opt-out-able.\n  // A question's sourceRef names the question, not its project, so the host\n  // resolves the project itself (scopeOf may be async).\n  isSuppressed: optOutSuppression(optOuts, async (request) => {\n    const projectId = await projectIdForSourceRef(request.tenantId, request.sourceRef);\n    return projectId ? `project:${projectId}` : null;\n  }),\n});\n```\n\nBecause the outbox re-checks at dispatch, an opt-out recorded after enqueue\ncancels the pending delivery before handoff. Tests:\n`src/__tests__/notification-opt-out*.test.ts`.\n\n## Schema\n\nNew tables `notification_opt_outs` (same rules) and `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": [

package/dist/smrt-knowledge.okf.md

@@ -5,10 +5,10 @@ description: "Unified multi-channel messaging with STI-based hierarchies"
 status: "stable"
 generated:
   by: "smrt/scripts/generate-knowledge-okf.ts"
-  at: "2026-11-05T21:47:30Z"
+  at: "2026-11-06T03:05:34Z"
 audience: "internal"
 evidence_level: "source-inspected"
-source_revision: "sha256:dd716664cbc58d30c87b791c0f570ef3a00c53dfdbaa8a5854baee9e0d7ac701"
+source_revision: "sha256:99b6d6b6c81224d0127273516be7be6b62754883c9b6b9d3ee4d1bc6db3e9222"
 sources:
   - id: "manifest"
     resource: "https://github.com/happyvertical/smrt/blob/main/packages/messages/package.json"
@@ -91,6 +91,8 @@ sources:
 - `MessagingEndpointCollection` (collection `messagingendpoints`, extends `SmrtCollection`)
 - `NotificationDelivery` (collection `notificationdeliveries`, extends `SmrtObject`)
 - `NotificationDeliveryCollection` (collection `notificationdeliveries`, extends `SmrtCollection`)
+- `NotificationOptOut` (collection `notificationoptouts`, extends `SmrtObject`)
+- `NotificationOptOutCollection` (collection `notificationoptouts`, extends `SmrtCollection`)
 - `PersonaMessageRoute` (collection `personamessageroutes`, extends `SmrtObject`)
 - `PersonaMessageRouteCollection` (collection `personamessageroutes`, extends `SmrtCollection`)
 - `SlackAccount` (collection `accounts`, extends `Account`, STI table)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-messages",
-  "version": "0.60.10",
+  "version": "0.60.11",
   "smrtJsdoc": "strict",
   "description": "Unified multi-channel messaging with STI-based hierarchies",
   "type": "module",
@@ -63,12 +63,12 @@
     "@happyvertical/files": "^0.111.5",
     "@happyvertical/logger": "^0.111.5",
     "@happyvertical/messages": "^0.111.5",
-    "@happyvertical/smrt-core": "0.60.10",
-    "@happyvertical/smrt-types": "0.60.10",
-    "@happyvertical/smrt-secrets": "0.60.10",
-    "@happyvertical/smrt-tenancy": "0.60.10",
-    "@happyvertical/smrt-ui": "0.60.10",
-    "@happyvertical/smrt-users": "0.60.10",
+    "@happyvertical/smrt-core": "0.60.11",
+    "@happyvertical/smrt-types": "0.60.11",
+    "@happyvertical/smrt-secrets": "0.60.11",
+    "@happyvertical/smrt-tenancy": "0.60.11",
+    "@happyvertical/smrt-ui": "0.60.11",
+    "@happyvertical/smrt-users": "0.60.11",
     "@happyvertical/sql": "^0.111.5",
     "@happyvertical/utils": "^0.111.5"
   },
@@ -85,8 +85,8 @@
     }
   },
   "devDependencies": {
-    "@happyvertical/smrt-ledgers": "0.60.10",
-    "@happyvertical/smrt-vitest": "0.60.10",
+    "@happyvertical/smrt-ledgers": "0.60.11",
+    "@happyvertical/smrt-vitest": "0.60.11",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.3.0",
     "@types/node": "24.13.6",