@cosmicdrift/kumiko-samples 0.405.0 → 0.409.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (242) hide show
  1. package/package.json +1 -1
  2. package/packages/bundled-features/package.json +26 -4
  3. package/packages/bundled-features/src/account-security/feature.ts +9 -1
  4. package/packages/bundled-features/src/admin-shell/changes.json +6 -0
  5. package/packages/bundled-features/src/admin-shell/feature.ts +4 -1
  6. package/packages/bundled-features/src/agent-tools/agent-manifest.ts +1 -0
  7. package/packages/bundled-features/src/agent-tools/changes.json +6 -0
  8. package/packages/bundled-features/src/agent-tools/tool-catalog.ts +1 -0
  9. package/packages/bundled-features/src/agent-tools/types.ts +4 -0
  10. package/packages/bundled-features/src/audit/event-classification.ts +1 -0
  11. package/packages/bundled-features/src/auth-email-password/bootstrap.ts +1 -0
  12. package/packages/bundled-features/src/auth-email-password/errors.ts +18 -66
  13. package/packages/bundled-features/src/auth-email-password/web/auth-client.ts +30 -64
  14. package/packages/bundled-features/src/auth-email-password/web/auth-redirect.ts +2 -2
  15. package/packages/bundled-features/src/auth-email-password/web/confirm-account-unlock-screen.tsx +20 -66
  16. package/packages/bundled-features/src/auth-email-password/web/index.ts +1 -0
  17. package/packages/bundled-features/src/auth-email-password/web/read-path-param.ts +8 -0
  18. package/packages/bundled-features/src/auth-email-password/web/return-path.ts +3 -2
  19. package/packages/bundled-features/src/auth-email-password/web/token-confirm-screen.tsx +97 -0
  20. package/packages/bundled-features/src/auth-email-password/web/verify-email-screen.tsx +20 -68
  21. package/packages/bundled-features/src/auth-foundation/boot-checks.ts +22 -15
  22. package/packages/bundled-features/src/auth-foundation/boot-rules.ts +33 -0
  23. package/packages/bundled-features/src/auth-mfa/errors.ts +12 -42
  24. package/packages/bundled-features/src/auth-mfa/feature-exports.ts +6 -45
  25. package/packages/bundled-features/src/auth-mfa/feature.ts +8 -19
  26. package/packages/bundled-features/src/auth-mfa/web/mfa-client.ts +19 -33
  27. package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-notify.ts +1 -0
  28. package/packages/bundled-features/src/billing-foundation/web/plan-price.ts +20 -7
  29. package/packages/bundled-features/src/cap-counter/stock-cap-guard.ts +1 -0
  30. package/packages/bundled-features/src/channel-in-app/changes.json +7 -0
  31. package/packages/bundled-features/src/channel-in-app/feature.ts +2 -0
  32. package/packages/bundled-features/src/channel-in-app/handlers/read-state-by-keys.query.ts +35 -0
  33. package/packages/bundled-features/src/channel-in-app/in-app-channel.ts +1 -0
  34. package/packages/bundled-features/src/channel-in-app/tables.ts +5 -1
  35. package/packages/bundled-features/src/contact/challenge.ts +41 -0
  36. package/packages/bundled-features/src/contact/changes.json +27 -0
  37. package/packages/bundled-features/src/contact/client/contact-client-source.ts +203 -0
  38. package/packages/bundled-features/src/contact/entity.ts +168 -0
  39. package/packages/bundled-features/src/contact/feature.ts +171 -0
  40. package/packages/bundled-features/src/contact/handlers/access.ts +17 -0
  41. package/packages/bundled-features/src/contact/handlers/attempts.ts +76 -0
  42. package/packages/bundled-features/src/contact/handlers/challenge.query.ts +44 -0
  43. package/packages/bundled-features/src/contact/handlers/forward-request.write.ts +98 -0
  44. package/packages/bundled-features/src/contact/handlers/mark-done.write.ts +40 -0
  45. package/packages/bundled-features/src/contact/handlers/notify-reporter-in-app.write.ts +48 -0
  46. package/packages/bundled-features/src/contact/handlers/open-count.query.ts +15 -0
  47. package/packages/bundled-features/src/contact/handlers/open-count.ts +17 -0
  48. package/packages/bundled-features/src/contact/handlers/replies.query.ts +29 -0
  49. package/packages/bundled-features/src/contact/handlers/reply.write.ts +197 -0
  50. package/packages/bundled-features/src/contact/handlers/report.write.ts +126 -0
  51. package/packages/bundled-features/src/contact/handlers/request-delivery.query.ts +143 -0
  52. package/packages/bundled-features/src/contact/handlers/request-detail.query.ts +50 -0
  53. package/packages/bundled-features/src/contact/handlers/request-list.query.ts +14 -0
  54. package/packages/bundled-features/src/contact/handlers/send-reply-mail.write.ts +124 -0
  55. package/packages/bundled-features/src/contact/handlers/send-test.write.ts +45 -0
  56. package/packages/bundled-features/src/contact/handlers/submit.write.ts +194 -0
  57. package/packages/bundled-features/src/contact/handlers/take-over-uploads.ts +47 -0
  58. package/packages/bundled-features/src/contact/i18n.ts +189 -0
  59. package/packages/bundled-features/src/contact/index.ts +29 -0
  60. package/packages/bundled-features/src/contact/lib.ts +176 -0
  61. package/packages/bundled-features/src/contact/mail.ts +401 -0
  62. package/packages/bundled-features/src/contact/options.ts +95 -0
  63. package/packages/bundled-features/src/contact/panels.ts +28 -0
  64. package/packages/bundled-features/src/contact/payloads.ts +106 -0
  65. package/packages/bundled-features/src/contact/pow.ts +22 -0
  66. package/packages/bundled-features/src/contact/screens.ts +506 -0
  67. package/packages/bundled-features/src/contact/subject.ts +13 -0
  68. package/packages/bundled-features/src/contact/user-agent.ts +39 -0
  69. package/packages/bundled-features/src/contact/user-data-hooks.ts +180 -0
  70. package/packages/bundled-features/src/contact/web/constants.ts +160 -0
  71. package/packages/bundled-features/src/contact/web/index.ts +29 -0
  72. package/packages/bundled-features/src/crypto-shredding/handlers/forget-subject.write.ts +5 -16
  73. package/packages/bundled-features/src/data-retention/changes.json +6 -0
  74. package/packages/bundled-features/src/data-retention/feature.ts +16 -2
  75. package/packages/bundled-features/src/data-retention/index.ts +5 -0
  76. package/packages/bundled-features/src/data-retention/run-retention-cleanup.ts +138 -41
  77. package/packages/bundled-features/src/data-retention/tenant-destruction-hold.ts +196 -0
  78. package/packages/bundled-features/src/delivery/address-opt-out.ts +1 -0
  79. package/packages/bundled-features/src/delivery/changes.json +7 -0
  80. package/packages/bundled-features/src/delivery/channel-context.ts +2 -0
  81. package/packages/bundled-features/src/delivery/delivery-service.ts +29 -5
  82. package/packages/bundled-features/src/delivery/events.ts +2 -0
  83. package/packages/bundled-features/src/delivery/feature.ts +3 -2
  84. package/packages/bundled-features/src/delivery/handlers/attempts-by-keys.query.ts +55 -0
  85. package/packages/bundled-features/src/delivery/handlers/log.query.ts +1 -1
  86. package/packages/bundled-features/src/delivery/jobs.ts +5 -0
  87. package/packages/bundled-features/src/delivery/tables.ts +13 -2
  88. package/packages/bundled-features/src/delivery/types.ts +3 -0
  89. package/packages/bundled-features/src/delivery/unsubscribe-page.ts +2 -0
  90. package/packages/bundled-features/src/delivery/web/delivery-channel-cell.tsx +1 -1
  91. package/packages/bundled-features/src/delivery/web/delivery-error-cell.tsx +1 -1
  92. package/packages/bundled-features/src/delivery/web/delivery-status-cell.tsx +1 -1
  93. package/packages/bundled-features/src/delivery/web/delivery-time-cell.tsx +3 -2
  94. package/packages/bundled-features/src/delivery/web/delivery-type-cell.tsx +1 -1
  95. package/packages/bundled-features/src/delivery/web/public-names.ts +1 -0
  96. package/packages/bundled-features/src/document-ingest-foundation/boot-checks.ts +14 -9
  97. package/packages/bundled-features/src/document-ingest-foundation/boot-rules.ts +22 -0
  98. package/packages/bundled-features/src/document-ingest-foundation/changes.json +6 -0
  99. package/packages/bundled-features/src/document-ingest-foundation/events.ts +17 -0
  100. package/packages/bundled-features/src/document-ingest-foundation/feature.ts +39 -1
  101. package/packages/bundled-features/src/document-ingest-foundation/index.ts +10 -0
  102. package/packages/bundled-features/src/document-ingest-foundation/report-ingest-progress.ts +43 -0
  103. package/packages/bundled-features/src/document-ingest-foundation/tables.ts +43 -0
  104. package/packages/bundled-features/src/files-tenant-data/changes.json +6 -0
  105. package/packages/bundled-features/src/files-tenant-data/hooks.ts +4 -1
  106. package/packages/bundled-features/src/folders/web/folder-manager.tsx +8 -9
  107. package/packages/bundled-features/src/folders/web/folder-section.tsx +1 -1
  108. package/packages/bundled-features/src/form-draft-user-data/index.ts +2 -0
  109. package/packages/bundled-features/src/inbound-mail-foundation/changes.json +13 -0
  110. package/packages/bundled-features/src/inbound-mail-foundation/entities.ts +2 -0
  111. package/packages/bundled-features/src/inbound-mail-foundation/events.ts +2 -0
  112. package/packages/bundled-features/src/inbound-mail-foundation/feature.ts +6 -6
  113. package/packages/bundled-features/src/inbound-mail-foundation/handlers/attach-message-content.write.ts +7 -0
  114. package/packages/bundled-features/src/inbound-mail-foundation/handlers/ingest-message.write.ts +6 -0
  115. package/packages/bundled-features/src/inbound-mail-foundation/handlers/list-messages.query.ts +6 -2
  116. package/packages/bundled-features/src/inbound-mail-foundation/handlers/message-content.query.ts +3 -0
  117. package/packages/bundled-features/src/inbound-mail-foundation/handlers/message-content.ts +19 -0
  118. package/packages/bundled-features/src/inbound-mail-foundation/projection.ts +2 -0
  119. package/packages/bundled-features/src/inbound-mail-foundation/sanitize-inbound-html.ts +150 -0
  120. package/packages/bundled-features/src/inbound-mail-foundation/types.ts +1 -0
  121. package/packages/bundled-features/src/jobs/job-run-logger.ts +24 -25
  122. package/packages/bundled-features/src/ledger/handlers/reports.query.ts +46 -31
  123. package/packages/bundled-features/src/ledger/recurring.ts +1 -0
  124. package/packages/bundled-features/src/notes-history/web/notes-section.tsx +3 -1
  125. package/packages/bundled-features/src/personal-access-tokens/feature.ts +9 -17
  126. package/packages/bundled-features/src/personal-access-tokens/handlers/create.write.ts +2 -7
  127. package/packages/bundled-features/src/secrets/changes.json +6 -0
  128. package/packages/bundled-features/src/secrets/handlers/delete.write.ts +8 -4
  129. package/packages/bundled-features/src/secrets/handlers/list.query.ts +6 -3
  130. package/packages/bundled-features/src/secrets/handlers/set.write.ts +9 -4
  131. package/packages/bundled-features/src/secrets/secret-scope.ts +33 -0
  132. package/packages/bundled-features/src/sessions/changes.json +6 -0
  133. package/packages/bundled-features/src/sessions/feature.ts +21 -18
  134. package/packages/bundled-features/src/sessions/handlers/last-activity-probe.query.ts +53 -0
  135. package/packages/bundled-features/src/sessions/handlers/last-activity-probe.route.ts +39 -0
  136. package/packages/bundled-features/src/sessions/screens.ts +1 -0
  137. package/packages/bundled-features/src/sessions/session-callbacks.ts +13 -12
  138. package/packages/bundled-features/src/sessions/web/i18n.ts +4 -1
  139. package/packages/bundled-features/src/shared/assert-billing-live.ts +14 -0
  140. package/packages/bundled-features/src/shared/collect-extension-options.ts +12 -0
  141. package/packages/bundled-features/src/shared/index.ts +16 -0
  142. package/packages/bundled-features/src/shared/late-bound-slot.ts +19 -0
  143. package/packages/bundled-features/src/shared/mail-locale-templates.ts +7 -1
  144. package/packages/bundled-features/src/shared/price-env-shape.ts +44 -0
  145. package/packages/bundled-features/src/shared/purge-row-file-refs.ts +1 -1
  146. package/packages/bundled-features/src/shared/read-feature-export-fn.ts +16 -0
  147. package/packages/bundled-features/src/shared/signup-handover.ts +3 -4
  148. package/packages/bundled-features/src/shared/tenant-destruction-hold.ts +49 -0
  149. package/packages/bundled-features/src/shared/unprocessable.ts +19 -0
  150. package/packages/bundled-features/src/shared/web/index.ts +3 -0
  151. package/packages/bundled-features/src/subscription-paddle/feature.ts +7 -15
  152. package/packages/bundled-features/src/subscription-paddle/runtime.ts +4 -7
  153. package/packages/bundled-features/src/subscription-stripe/feature.ts +7 -15
  154. package/packages/bundled-features/src/subscription-stripe/runtime.ts +4 -7
  155. package/packages/bundled-features/src/tags/entity.ts +1 -0
  156. package/packages/bundled-features/src/tags/web/tag-chip.tsx +14 -0
  157. package/packages/bundled-features/src/tags/web/tag-filter.tsx +4 -5
  158. package/packages/bundled-features/src/tags/web/tag-manager.tsx +1 -1
  159. package/packages/bundled-features/src/tags/web/tag-section.tsx +3 -6
  160. package/packages/bundled-features/src/tags/web/tags-cell.tsx +4 -5
  161. package/packages/bundled-features/src/template-resolver/compile-document-body.ts +27 -15
  162. package/packages/bundled-features/src/template-resolver/handlers/by-tenant.query.ts +11 -8
  163. package/packages/bundled-features/src/template-resolver/handlers/discard-draft.write.ts +1 -0
  164. package/packages/bundled-features/src/template-resolver/handlers/overview.query.ts +1 -0
  165. package/packages/bundled-features/src/template-resolver/handlers/send-test.write.ts +5 -5
  166. package/packages/bundled-features/src/template-resolver/handlers/toggle-status.write.ts +3 -0
  167. package/packages/bundled-features/src/template-resolver/linked-resources.ts +11 -6
  168. package/packages/bundled-features/src/template-resolver/store-template-resource.ts +15 -12
  169. package/packages/bundled-features/src/template-resolver/web/document-images.ts +6 -6
  170. package/packages/bundled-features/src/template-resolver/web/document-insert-fields.tsx +41 -36
  171. package/packages/bundled-features/src/template-resolver/web/document-schema.ts +11 -12
  172. package/packages/bundled-features/src/template-resolver/web/tiptap-attribute-parse-rule.ts +19 -0
  173. package/packages/bundled-features/src/tenant/i18n.ts +3 -0
  174. package/packages/bundled-features/src/tenant/schema/tenant.ts +1 -0
  175. package/packages/bundled-features/src/tenant/web/member-roles-cell.tsx +1 -1
  176. package/packages/bundled-features/src/tenant/web/member-status-cell.tsx +1 -1
  177. package/packages/bundled-features/src/tenant-inactivity/changes.json +8 -0
  178. package/packages/bundled-features/src/tenant-inactivity/check-inactive-tenants.ts +260 -0
  179. package/packages/bundled-features/src/tenant-inactivity/constants.ts +12 -0
  180. package/packages/bundled-features/src/tenant-inactivity/email-templates.ts +24 -0
  181. package/packages/bundled-features/src/tenant-inactivity/feature.ts +66 -0
  182. package/packages/bundled-features/src/tenant-inactivity/handlers/inactivity-state.query.ts +49 -0
  183. package/packages/bundled-features/src/tenant-inactivity/handlers/keep-account.write.ts +56 -0
  184. package/packages/bundled-features/src/tenant-inactivity/inactivity-plan.ts +187 -0
  185. package/packages/bundled-features/src/tenant-inactivity/index.ts +5 -0
  186. package/packages/bundled-features/src/tenant-inactivity/keep-token.ts +44 -0
  187. package/packages/bundled-features/src/tenant-inactivity/mail-notifications.ts +62 -0
  188. package/packages/bundled-features/src/tenant-inactivity/options.ts +38 -0
  189. package/packages/bundled-features/src/tenant-inactivity/remote-activity.ts +32 -0
  190. package/packages/bundled-features/src/tenant-inactivity/state-store.ts +71 -0
  191. package/packages/bundled-features/src/tenant-inactivity/state-table.ts +50 -0
  192. package/packages/bundled-features/src/tenant-lifecycle/boot-checks.ts +8 -6
  193. package/packages/bundled-features/src/tenant-lifecycle/boot-rules.ts +16 -0
  194. package/packages/bundled-features/src/tenant-lifecycle/changes.json +30 -0
  195. package/packages/bundled-features/src/tenant-lifecycle/constants.ts +6 -0
  196. package/packages/bundled-features/src/tenant-lifecycle/events.ts +2 -0
  197. package/packages/bundled-features/src/tenant-lifecycle/feature.ts +25 -2
  198. package/packages/bundled-features/src/tenant-lifecycle/handlers/request-destruction.write.ts +12 -87
  199. package/packages/bundled-features/src/tenant-lifecycle/index.ts +6 -0
  200. package/packages/bundled-features/src/tenant-lifecycle/request-tenant-destruction.ts +108 -0
  201. package/packages/bundled-features/src/tenant-lifecycle/retention-config-destroy-hooks.ts +62 -0
  202. package/packages/bundled-features/src/tenant-lifecycle/run-tenant-destroy.ts +131 -11
  203. package/packages/bundled-features/src/tenant-lifecycle/stages.ts +39 -4
  204. package/packages/bundled-features/src/tenant-lifecycle/testing.ts +1 -1
  205. package/packages/bundled-features/src/tier-engine/caps-for-tier-from-map.ts +16 -0
  206. package/packages/bundled-features/src/tier-engine/changes.json +6 -0
  207. package/packages/bundled-features/src/tier-engine/compose-app.ts +21 -20
  208. package/packages/bundled-features/src/tier-engine/index.ts +1 -0
  209. package/packages/bundled-features/src/user-data-rights/feature.ts +2 -0
  210. package/packages/bundled-features/src/user-data-rights/run-forget-cleanup.ts +2 -0
  211. package/packages/bundled-features/src/user-data-rights/web/privacy-center-screen.tsx +1 -1
  212. package/packages/bundled-features/src/user-data-rights/zip-path.ts +1 -0
  213. package/packages/bundled-features/src/user-data-rights-defaults/hooks/config-value.userdata-hook.ts +8 -27
  214. package/packages/bundled-features/src/user-data-rights-defaults/hooks/delivery-attempt.userdata-hook.ts +11 -8
  215. package/packages/bundled-features/src/user-data-rights-defaults/hooks/forget-own-rows-delete-hook.ts +42 -0
  216. package/packages/bundled-features/src/user-data-rights-defaults/hooks/notification-preference.userdata-hook.ts +8 -27
  217. package/packages/bundled-features/src/user-profile/handlers/change-email.write.ts +2 -6
  218. package/packages/bundled-features/src/user-profile/web/profile-screen.tsx +2 -3
  219. package/samples/apps/styleguide/src/features/widgets/i18n.ts +6 -0
  220. package/samples/apps/styleguide/src/features/widgets/web/InboxReaderExamples.tsx +158 -0
  221. package/samples/apps/styleguide/src/features/widgets/web/Widgets.tsx +2 -0
  222. package/samples/apps/styleguide/src/features/widgets/web/sample-pdf.ts +28 -0
  223. package/samples/apps/use-all-bundled/feature-manifest.json +134 -2
  224. package/samples/apps/use-all-bundled/kumiko/migrations/0063_contact.rebuild.json +4 -0
  225. package/samples/apps/use-all-bundled/package.json +1 -0
  226. package/samples/apps/use-all-bundled/playwright.config.ts +2 -0
  227. package/samples/apps/use-all-bundled/src/app/client.tsx +3 -0
  228. package/samples/apps/use-all-bundled/src/app/screens-feature.ts +46 -2
  229. package/samples/apps/use-all-bundled/src/run-config.ts +38 -4
  230. package/samples/recipes/contact/README.md +46 -0
  231. package/samples/recipes/contact/package.json +12 -0
  232. package/samples/recipes/contact/src/feature.ts +27 -0
  233. package/samples/recipes/delivery-notifications/src/feature.ts +3 -0
  234. package/samples/recipes/lane-routing/README.md +1 -0
  235. package/samples/recipes/lane-routing/src/feature.ts +8 -0
  236. package/samples/recipes/record-detail-layout/src/feature.ts +9 -1
  237. package/samples/recipes/search/README.md +2 -0
  238. package/samples/recipes/search/src/feature.ts +27 -2
  239. package/samples/recipes/secrets-demo/README.md +1 -0
  240. package/samples/recipes/secrets-demo/src/feature.ts +56 -0
  241. package/samples/recipes/tenant-inactivity/README.md +21 -0
  242. package/samples/recipes/tenant-inactivity/package.json +12 -0
@@ -40,9 +40,11 @@
40
40
  import {
41
41
  collectPiiSubjectFields,
42
42
  configuredPiiSubjectKms,
43
+ isPiiCiphertext,
43
44
  isRecordKeyedField,
44
45
  isSelfPiiField,
45
46
  type KmsAdapter,
47
+ PII_ERASED_SENTINEL,
46
48
  resolveSubjectForField,
47
49
  type SubjectId,
48
50
  subjectIdToKey,
@@ -73,9 +75,11 @@ import {
73
75
  fileRefEntity,
74
76
  fileRefsTable,
75
77
  } from "@cosmicdrift/kumiko-framework/files";
78
+ import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
76
79
  import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
77
80
  import {
78
81
  collectSingleFileHolders,
82
+ decryptStoredPii,
79
83
  planFileFields,
80
84
  purgeRowFileRefs,
81
85
  runInSubTransaction,
@@ -86,8 +90,10 @@ import type { RetentionPresetKey } from "./presets.ts";
86
90
  import { resolveRetentionPolicyForTenant } from "./resolve-for-tenant.ts";
87
91
  import { tenantRetentionOverrideTable } from "./schema/tenant-retention-override.ts";
88
92
 
93
+ const log = createFallbackLogger("data-retention");
94
+
89
95
  const DEFAULT_BATCH_LIMIT = 1000;
90
- const DEFAULT_REFERENCE_FIELD = "createdAt";
96
+ export const DEFAULT_REFERENCE_FIELD = "createdAt";
91
97
 
92
98
  // The boot validator (boot-validator/pii-retention.ts FRAMEWORK_TIMESTAMP_FIELDS)
93
99
  // permits these aliases as retention.reference even when they are not declared in
@@ -96,7 +102,7 @@ const DEFAULT_REFERENCE_FIELD = "createdAt";
96
102
  // during cleanup; otherwise the column existence check below would cause the cron
97
103
  // to do nothing silently. deletedAt/lastSeenAt are real fields (softDelete and
98
104
  // session respectively) and need no translation.
99
- const FRAMEWORK_REFERENCE_ALIAS: Readonly<Record<string, string>> = {
105
+ export const FRAMEWORK_REFERENCE_ALIAS: Readonly<Record<string, string>> = {
100
106
  createdAt: "insertedAt",
101
107
  updatedAt: "modifiedAt",
102
108
  };
@@ -113,6 +119,9 @@ export interface RunRetentionCleanupArgs {
113
119
  */
114
120
  readonly now: Instant;
115
121
  readonly batchLimit?: number;
122
+ /** Tenant is being destroyed and only kept alive by its blockDelete rows: expired ones are
123
+ * deleted instead of anonymized. */
124
+ readonly purgeExpiredBlockDelete?: boolean;
116
125
  /** Storage access for hardDelete entities with file/image/files/images fields.
117
126
  * Missing while fileRefs are due → the row stays (skipped "missing_file_storage"),
118
127
  * fail-closed instead of orphaning bytes. */
@@ -314,6 +323,7 @@ async function purgeHardDeleteRowWithFiles(args: {
314
323
  readonly tdb: TenantDb;
315
324
  readonly kms: KmsAdapter | undefined;
316
325
  readonly registry: Registry;
326
+ readonly deleteWithoutFileStorage: boolean;
317
327
  readonly onSkip: (reason: "missing_file_storage" | "file_delete_failed") => void;
318
328
  }): Promise<boolean> {
319
329
  const logContext = `tenant=${args.tenantId} entity=${args.entityName} row=${String(args.rowId)}`;
@@ -326,7 +336,14 @@ async function purgeHardDeleteRowWithFiles(args: {
326
336
  table: args.table,
327
337
  fileHolders: args.fileHolders,
328
338
  row: args.row,
329
- deleteBytes: files ? (key) => deleteFileFailingClosed(key, files, logContext) : undefined,
339
+ deleteBytes: files
340
+ ? (key) => deleteFileFailingClosed(key, files, logContext)
341
+ : args.deleteWithoutFileStorage
342
+ ? async (key) => {
343
+ log.warn(`${logContext} no file storage wired, bytes of ${key} are not deleted`);
344
+ return [];
345
+ }
346
+ : undefined,
330
347
  fileRefForget: async (fileRefId) =>
331
348
  (await args.fileRefExecutor.forget({ id: fileRefId }, args.systemUser, args.tdb)).isSuccess,
332
349
  onBytesDeleteFailed: (failedKeys) => {
@@ -376,6 +393,7 @@ async function purgeHardDeleteRowsWithFiles(args: {
376
393
  readonly tdb: TenantDb;
377
394
  readonly kms: KmsAdapter | undefined;
378
395
  readonly registry: Registry;
396
+ readonly deleteWithoutFileStorage: boolean;
379
397
  readonly skipped: RetentionCleanupSkip[];
380
398
  }): Promise<number> {
381
399
  const reasonsSeen = new Set<RetentionCleanupSkip["reason"]>();
@@ -424,6 +442,7 @@ async function purgeHardDeleteRowsWithFiles(args: {
424
442
  tdb: args.tdb,
425
443
  kms: args.kms,
426
444
  registry: args.registry,
445
+ deleteWithoutFileStorage: args.deleteWithoutFileStorage,
427
446
  onSkip,
428
447
  });
429
448
  if (ok) count++;
@@ -440,7 +459,7 @@ type AnonymizeCapableField = { readonly anonymize?: () => unknown | Promise<unkn
440
459
  // Evaluate the entity's per-field anonymize functions ONCE — they are
441
460
  // row-independent by signature, so the result doubles as the idempotency
442
461
  // probe: a row already carrying these values needs no event.
443
- async function resolveAnonymizeTargets(
462
+ export async function resolveAnonymizeTargets(
444
463
  fields: Readonly<Record<string, unknown>>,
445
464
  ): Promise<Record<string, unknown> | null> {
446
465
  const targets: Record<string, unknown> = {};
@@ -451,11 +470,20 @@ async function resolveAnonymizeTargets(
451
470
  return Object.keys(targets).length > 0 ? targets : null;
452
471
  }
453
472
 
454
- function rowNeedsAnonymize(
473
+ // Encrypted PII is stored as ciphertext, so the diff has to compare the decrypted value; an erased
474
+ // subject key reads back as the sentinel and counts as anonymized already.
475
+ async function rowNeedsAnonymize(
455
476
  row: Record<string, unknown>,
456
477
  targets: Record<string, unknown>,
457
- ): boolean {
458
- return Object.entries(targets).some(([field, value]) => row[field] !== value);
478
+ ): Promise<boolean> {
479
+ for (const [field, target] of Object.entries(targets)) {
480
+ const stored = row[field];
481
+ const current = isPiiCiphertext(stored)
482
+ ? await decryptStoredPii(stored, field, "retention-anonymize")
483
+ : stored;
484
+ if (current !== PII_ERASED_SENTINEL && current !== target) return true;
485
+ }
486
+ return false;
459
487
  }
460
488
 
461
489
  // Anonymize every matching row via the executor (event → rebuild-safe).
@@ -464,7 +492,7 @@ function rowNeedsAnonymize(
464
492
  // UPDATES per run, not the scan.
465
493
  // ponytail: scans all past-cutoff rows per run — add an anonymized-marker
466
494
  // column if a hot entity accumulates millions of held rows.
467
- async function anonymizeMatchingRows(
495
+ export async function anonymizeMatchingRows(
468
496
  db: DbRunner,
469
497
  table: Parameters<typeof selectMany>[1],
470
498
  where: WhereObject,
@@ -483,7 +511,7 @@ async function anonymizeMatchingRows(
483
511
  if (rows.length === 0) break;
484
512
  for (const row of rows) {
485
513
  cursor = row["id"] as EntityId; // @cast-boundary db-row
486
- if (!rowNeedsAnonymize(row, targets)) continue;
514
+ if (!(await rowNeedsAnonymize(row, targets))) continue;
487
515
  const res = await op(cursor, targets);
488
516
  if (res.isSuccess) count++;
489
517
  if (count >= batchLimit) break;
@@ -492,6 +520,81 @@ async function anonymizeMatchingRows(
492
520
  return count;
493
521
  }
494
522
 
523
+ export async function loadOverrideByEntity(
524
+ db: DbRunner,
525
+ tenantId: TenantId,
526
+ ): Promise<ReadonlyMap<string, { config: string | null }>> {
527
+ const overrideRows = await selectMany<{ entityName: string; config: string | null }>(
528
+ db,
529
+ tenantRetentionOverrideTable,
530
+ { tenantId },
531
+ );
532
+ return new Map(overrideRows.map((r) => [r.entityName, { config: r.config }]));
533
+ }
534
+
535
+ async function hardDeleteMatchingRows(args: {
536
+ readonly db: DbRunner;
537
+ readonly table: Parameters<typeof selectMany>[1];
538
+ readonly where: WhereObject;
539
+ readonly batchLimit: number;
540
+ readonly tenantId: TenantId;
541
+ readonly entityName: string;
542
+ readonly entity: EntityDefinition;
543
+ readonly files: FileContext | undefined;
544
+ readonly systemUser: SessionUser;
545
+ readonly tdb: TenantDb;
546
+ readonly kms: KmsAdapter | undefined;
547
+ readonly registry: Registry;
548
+ readonly fileHolders: readonly SingleFileHolder[];
549
+ // A tenant being destroyed has nothing left to keep file bytes for; without storage the rows go
550
+ // anyway, otherwise the destruction would wait forever for a provider that is not coming.
551
+ readonly deleteWithoutFileStorage: boolean;
552
+ readonly skipped: RetentionCleanupSkip[];
553
+ }): Promise<number> {
554
+ const executor = createEventStoreExecutor(args.table, args.entity, {
555
+ entityName: args.entityName,
556
+ });
557
+ const filePlan = planFileFields(args.entity.fields);
558
+ if (filePlan.singleFields.length === 0 && filePlan.multiFields.length === 0) {
559
+ return await purgeMatchingRows(args.db, args.table, args.where, args.batchLimit, (id) =>
560
+ forgetRowAndEraseKeys({
561
+ db: args.db,
562
+ executor,
563
+ entity: args.entity,
564
+ entityName: args.entityName,
565
+ tenantId: args.tenantId,
566
+ systemUser: args.systemUser,
567
+ rowId: id,
568
+ row: { id },
569
+ kms: args.kms,
570
+ registry: args.registry,
571
+ }),
572
+ );
573
+ }
574
+ const fileRefExecutor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
575
+ entityName: "fileRef",
576
+ });
577
+ return await purgeHardDeleteRowsWithFiles({
578
+ db: args.db,
579
+ table: args.table,
580
+ fileHolders: args.fileHolders,
581
+ where: args.where,
582
+ batchLimit: args.batchLimit,
583
+ tenantId: args.tenantId,
584
+ entityName: args.entityName,
585
+ entity: args.entity,
586
+ files: args.files,
587
+ entityExecutor: executor,
588
+ fileRefExecutor,
589
+ systemUser: args.systemUser,
590
+ tdb: args.tdb,
591
+ kms: args.kms,
592
+ registry: args.registry,
593
+ deleteWithoutFileStorage: args.deleteWithoutFileStorage,
594
+ skipped: args.skipped,
595
+ });
596
+ }
597
+
495
598
  export async function runRetentionCleanup(
496
599
  args: RunRetentionCleanupArgs,
497
600
  ): Promise<RunRetentionCleanupResult> {
@@ -524,12 +627,7 @@ export async function runRetentionCleanup(
524
627
  // Pre-load every override row for this tenant ONCE — N entities × M
525
628
  // tenants would otherwise mean one fetchOne per entity per tenant, even
526
629
  // though the whole set for a tenant is a single small, indexed read.
527
- const overrideRows = await selectMany<{ entityName: string; config: string | null }>(
528
- db,
529
- tenantRetentionOverrideTable,
530
- { tenantId },
531
- );
532
- const overrideByEntity = new Map(overrideRows.map((r) => [r.entityName, { config: r.config }]));
630
+ const overrideByEntity = await loadOverrideByEntity(db, tenantId);
533
631
 
534
632
  for (const proj of registry.getAllProjections().values()) {
535
633
  // Only implicit entity projections with a table are targets, as in
@@ -570,44 +668,21 @@ export async function runRetentionCleanup(
570
668
 
571
669
  switch (policy.strategy) {
572
670
  case "hardDelete": {
573
- const executor = createEventStoreExecutor(proj.table, entity, { entityName });
574
- const filePlan = planFileFields(entity.fields);
575
- if (filePlan.singleFields.length === 0 && filePlan.multiFields.length === 0) {
576
- hardDeleted += await purgeMatchingRows(db, proj.table, where, batchLimit, (id) =>
577
- forgetRowAndEraseKeys({
578
- db,
579
- executor,
580
- entity,
581
- entityName,
582
- tenantId,
583
- systemUser,
584
- rowId: id,
585
- row: { id },
586
- kms,
587
- registry,
588
- }),
589
- );
590
- break;
591
- }
592
- const fileRefExecutor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
593
- entityName: "fileRef",
594
- });
595
- hardDeleted += await purgeHardDeleteRowsWithFiles({
671
+ hardDeleted += await hardDeleteMatchingRows({
596
672
  db,
597
673
  table: proj.table,
598
- fileHolders,
599
674
  where,
600
675
  batchLimit,
601
676
  tenantId,
602
677
  entityName,
603
678
  entity,
604
679
  files: args.files,
605
- entityExecutor: executor,
606
- fileRefExecutor,
607
680
  systemUser,
608
681
  tdb,
609
682
  kms,
610
683
  registry,
684
+ fileHolders,
685
+ deleteWithoutFileStorage: false,
611
686
  skipped,
612
687
  });
613
688
  break;
@@ -639,6 +714,28 @@ export async function runRetentionCleanup(
639
714
  // anonymize strategy, so both cases share it.
640
715
  case "anonymize":
641
716
  case "blockDelete": {
717
+ // A tenant held in destroyHeld has its expired blockDelete rows removed for good;
718
+ // anonymizing them would keep the account's data stored for nothing.
719
+ if (policy.strategy === "blockDelete" && args.purgeExpiredBlockDelete === true) {
720
+ hardDeleted += await hardDeleteMatchingRows({
721
+ db,
722
+ table: proj.table,
723
+ where,
724
+ batchLimit,
725
+ tenantId,
726
+ entityName,
727
+ entity,
728
+ files: args.files,
729
+ systemUser,
730
+ tdb,
731
+ kms,
732
+ registry,
733
+ fileHolders,
734
+ deleteWithoutFileStorage: true,
735
+ skipped,
736
+ });
737
+ break;
738
+ }
642
739
  const targets = await resolveAnonymizeTargets(entity.fields);
643
740
  if (!targets) {
644
741
  // blockDelete without anonymize fields is a pure hold only while the
@@ -0,0 +1,196 @@
1
+ // blockDelete rows of a tenant under destruction: the mandatory retention period outlives the account.
2
+ // The tenant-lifecycle destroy pipeline keeps those rows (anonymized) and parks the tenant until the
3
+ // retention cleanup has removed them.
4
+
5
+ import {
6
+ createEventStoreExecutor,
7
+ createTenantDb,
8
+ type DbRunner,
9
+ selectMany,
10
+ type WhereObject,
11
+ WritePurposes,
12
+ } from "@cosmicdrift/kumiko-framework/db";
13
+ import {
14
+ createSystemUser,
15
+ type EntityDefinition,
16
+ type Registry,
17
+ type TenantId,
18
+ } from "@cosmicdrift/kumiko-framework/engine";
19
+ import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
20
+ import { collectFileRefIds, planFileFields } from "../shared/index.ts";
21
+ import { computeCutoff, type Instant } from "./keep-for.ts";
22
+ import { resolveRetentionPolicyForTenant } from "./resolve-for-tenant.ts";
23
+ import { resolveTenantRetentionPreset } from "./resolve-tenant-preset.ts";
24
+ import {
25
+ anonymizeMatchingRows,
26
+ DEFAULT_REFERENCE_FIELD,
27
+ FRAMEWORK_REFERENCE_ALIAS,
28
+ loadOverrideByEntity,
29
+ resolveAnonymizeTargets,
30
+ } from "./run-retention-cleanup.ts";
31
+
32
+ const ANONYMIZE_PAGE_SIZE = 1000;
33
+
34
+ type ProjectionTable = Parameters<typeof selectMany>[1];
35
+
36
+ type BlockDeleteEntity = {
37
+ readonly entityName: string;
38
+ readonly entity: EntityDefinition;
39
+ readonly table: ProjectionTable;
40
+ readonly referenceField: string;
41
+ readonly cutoff: Instant;
42
+ };
43
+
44
+ type TenantHoldArgs = {
45
+ readonly db: DbRunner;
46
+ readonly registry: Registry;
47
+ readonly tenantId: TenantId;
48
+ readonly now: Instant;
49
+ };
50
+
51
+ async function collectBlockDeleteEntities(args: TenantHoldArgs): Promise<BlockDeleteEntity[]> {
52
+ const { db, registry, tenantId, now } = args;
53
+ const preloadedTenantPreset = await resolveTenantRetentionPreset({ db, registry, tenantId });
54
+ const overrideByEntity = await loadOverrideByEntity(db, tenantId);
55
+ const found: BlockDeleteEntity[] = [];
56
+ for (const proj of registry.getAllProjections().values()) {
57
+ if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table) continue;
58
+ const entityName = proj.source;
59
+ const entity = registry.getEntity(entityName);
60
+ if (!entity) continue;
61
+ const { policy } = await resolveRetentionPolicyForTenant({
62
+ db,
63
+ registry,
64
+ tenantId,
65
+ entityName,
66
+ preloadedTenantPreset,
67
+ preloadedOverride: overrideByEntity.get(entityName) ?? null,
68
+ });
69
+ if (policy?.strategy !== "blockDelete") continue;
70
+ // Rows of an entity without tenantId column cannot be attributed to this tenant.
71
+ if (propertyOf(proj.table, "tenantId") === undefined) continue;
72
+ const declaredReference = policy.reference ?? DEFAULT_REFERENCE_FIELD;
73
+ const referenceField = FRAMEWORK_REFERENCE_ALIAS[declaredReference] ?? declaredReference;
74
+ if (propertyOf(proj.table, referenceField) === undefined) continue;
75
+ found.push({
76
+ entityName,
77
+ entity,
78
+ table: proj.table,
79
+ referenceField,
80
+ cutoff: computeCutoff(policy.keepFor, now),
81
+ });
82
+ }
83
+ return found;
84
+ }
85
+
86
+ async function hasAnyRow(
87
+ db: DbRunner,
88
+ table: ProjectionTable,
89
+ where: WhereObject,
90
+ ): Promise<boolean> {
91
+ return (await selectMany(db, table, where, { limit: 1 })).length > 0;
92
+ }
93
+
94
+ /** True while the tenant still owns rows in an entity whose resolved policy is blockDelete. */
95
+ export async function tenantHasBlockDeleteRows(args: TenantHoldArgs): Promise<boolean> {
96
+ for (const held of await collectBlockDeleteEntities(args)) {
97
+ if (await hasAnyRow(args.db, held.table, { tenantId: args.tenantId })) return true;
98
+ }
99
+ return false;
100
+ }
101
+
102
+ export type DestructionHold = {
103
+ readonly entityNames: ReadonlySet<string>;
104
+ /** fileRefs the held rows point at: their rows and bytes must outlive the destruction too. */
105
+ readonly fileRefIds: ReadonlySet<string>;
106
+ };
107
+
108
+ async function collectHeldRowFileRefIds(
109
+ args: TenantHoldArgs,
110
+ held: BlockDeleteEntity,
111
+ into: Set<string>,
112
+ ): Promise<void> {
113
+ const plan = planFileFields(held.entity.fields);
114
+ // skip: an entity without file fields cannot point at a fileRef
115
+ if (plan.singleFields.length === 0 && plan.multiFields.length === 0) return;
116
+ let cursor: string | undefined;
117
+ for (;;) {
118
+ const where: WhereObject =
119
+ cursor === undefined
120
+ ? { tenantId: args.tenantId }
121
+ : { tenantId: args.tenantId, id: { gt: cursor } };
122
+ const rows = await selectMany<Record<string, unknown>>(args.db, held.table, where, {
123
+ limit: ANONYMIZE_PAGE_SIZE,
124
+ orderBy: { col: "id" },
125
+ });
126
+ // skip: the cursor walked past the last held row
127
+ if (rows.length === 0) return;
128
+ for (const row of rows) {
129
+ for (const id of await collectFileRefIds(
130
+ args.db,
131
+ args.tenantId,
132
+ held.entityName,
133
+ row,
134
+ plan,
135
+ )) {
136
+ into.add(id);
137
+ }
138
+ }
139
+ cursor = String(rows[rows.length - 1]?.["id"]);
140
+ }
141
+ }
142
+
143
+ /**
144
+ * Entities of the tenant with at least one blockDelete row still inside keepFor. All tenant rows of
145
+ * those entities get their personal fields anonymized (idempotent: already anonymized rows emit no
146
+ * event) and stay; the caller must not delete them, nor the fileRefs they point at.
147
+ */
148
+ export async function holdBlockDeleteRowsForDestruction(
149
+ args: TenantHoldArgs,
150
+ ): Promise<DestructionHold> {
151
+ const heldEntityNames = new Set<string>();
152
+ const heldFileRefIds = new Set<string>();
153
+ const systemUser = createSystemUser(args.tenantId);
154
+ const tdb = createTenantDb({
155
+ db: args.db,
156
+ tenantId: args.tenantId,
157
+ mode: "system",
158
+ reason: "tenant destruction anonymizes retention-held rows of the tenant being destroyed",
159
+ });
160
+ for (const candidate of await collectBlockDeleteEntities(args)) {
161
+ const { entityName, entity, table } = candidate;
162
+ const stillInsideKeepFor = await hasAnyRow(args.db, table, {
163
+ tenantId: args.tenantId,
164
+ [candidate.referenceField]: { gte: candidate.cutoff },
165
+ });
166
+ if (!stillInsideKeepFor) continue;
167
+ heldEntityNames.add(entityName);
168
+ await collectHeldRowFileRefIds(args, candidate, heldFileRefIds);
169
+ const targets = await resolveAnonymizeTargets(entity.fields);
170
+ if (!targets) continue;
171
+ const executor = createEventStoreExecutor(table, entity, { entityName });
172
+ let updated = ANONYMIZE_PAGE_SIZE;
173
+ while (updated === ANONYMIZE_PAGE_SIZE) {
174
+ updated = await anonymizeMatchingRows(
175
+ args.db,
176
+ table,
177
+ { tenantId: args.tenantId },
178
+ ANONYMIZE_PAGE_SIZE,
179
+ targets,
180
+ async (id, changes) => {
181
+ const result = await executor.update({ id, changes }, systemUser, tdb, {
182
+ skipOptimisticLock: true,
183
+ writePurpose: WritePurposes.retention,
184
+ });
185
+ if (!result.isSuccess) {
186
+ throw new Error(
187
+ `data-retention: failed to anonymize held ${entityName} row ${String(id)}: ${result.error.message}`,
188
+ );
189
+ }
190
+ return result;
191
+ },
192
+ );
193
+ }
194
+ }
195
+ return { entityNames: heldEntityNames, fileRefIds: heldFileRefIds };
196
+ }
@@ -35,6 +35,7 @@ export type UpsertAddressOptOutInput = {
35
35
 
36
36
  type OptOutLookupRow = { readonly id: string };
37
37
 
38
+ // guard:dup-ok fetchOne over this table's own business key; the preference lookup reads another table
38
39
  async function lookup(
39
40
  db: TenantDb,
40
41
  tenantId: TenantId,
@@ -1,4 +1,11 @@
1
1
  [
2
+ {
3
+ "version": "0.409.0",
4
+ "type": "improvement",
5
+ "title": "Delivery attempts remember the notify idempotencyKey; new attempts-by-keys query",
6
+ "detail": "`store_delivery_attempts` gets a nullable text column `idempotency_key` plus the non-unique index `(tenant_id, idempotency_key)`. Every attempt a `ctx.notify` call logs carries the call's `idempotencyKey` (the first event of an attempt stores it; later sent/failed events keep the row's value). The new SystemAdmin query `delivery:query:attempts-by-keys` (`{ keys: string[] }`, 1 to 50) returns channel, status, error code, time and recipient id of those attempts across tenants, never an address. Attempts logged before this version keep `idempotency_key = null`.",
7
+ "migration": "Run `kumiko schema generate`. It adds the nullable column `idempotency_key` to `store_delivery_attempts` and the index `store_delivery_attempts_tenant_id_idempotency_key_idx`. No backfill is needed; do not write the column with SQL. Every app that mounts delivery needs this migration when it bumps."
8
+ },
2
9
  {
3
10
  "version": "0.389.0",
4
11
  "type": "fix",
@@ -152,6 +152,7 @@ export function buildChannelContext(
152
152
  secrets?: SecretsContext,
153
153
  tenantConfig?: ConfigAccessor,
154
154
  filesForTenant?: (tenantId: string) => FileContext | undefined,
155
+ idempotencyKey?: string,
155
156
  ): ChannelContext {
156
157
  return {
157
158
  db: createTenantDb({ db, tenantId }),
@@ -160,6 +161,7 @@ export function buildChannelContext(
160
161
  tenantId,
161
162
  secrets,
162
163
  config: tenantConfig,
164
+ ...(idempotencyKey !== undefined && { idempotencyKey }),
163
165
  renderMail: createTemplateMailRenderer(db, registry, tenantId, tenantConfig),
164
166
  ...(filesForTenant !== undefined && {
165
167
  readAttachment: createEmailAttachmentReader(
@@ -324,9 +324,12 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
324
324
  readonly deliveries: NotifyDelivery[];
325
325
  readonly jobDispatcher: NotifyJobDispatcher | undefined;
326
326
  readonly locale: string | undefined;
327
+ readonly channelNames: ReadonlySet<string> | undefined;
327
328
  // Set only when exactly one channel carries the call: the queued job may then free
328
329
  // the key on terminal failure without risking a duplicate send on another channel.
329
330
  readonly jobIdempotencyKey: string | undefined;
331
+ // The caller's key as given, stamped on every attempt the call logs.
332
+ readonly idempotencyKey: string | undefined;
330
333
  readonly filesForTenant: ((tenantId: string) => FileContext | undefined) | undefined;
331
334
  };
332
335
 
@@ -348,9 +351,16 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
348
351
  // Single-shot terminal log (inline channels, skips, idempotency dups). Async
349
352
  // attempts instead append a queued event up front and a terminal event from
350
353
  // the send job — see deliverViaChannel + jobs.ts.
354
+ function withIdempotencyKey(run: NotifyRun, entry: DeliveryLogEntry): DeliveryLogEntry {
355
+ return run.idempotencyKey === undefined
356
+ ? entry
357
+ : { ...entry, idempotencyKey: run.idempotencyKey };
358
+ }
359
+
351
360
  async function logDelivery(run: NotifyRun, entry: DeliveryLogEntry): Promise<void> {
352
- const attemptId = await logAttempt(run.db, registry, entry);
353
- recordDelivery(run, entry, attemptId);
361
+ const stamped = withIdempotencyKey(run, entry);
362
+ const attemptId = await logAttempt(run.db, registry, stamped);
363
+ recordDelivery(run, stamped, attemptId);
354
364
  }
355
365
 
356
366
  // The stored/returned error is only the code; the redacted message goes to the log.
@@ -426,7 +436,12 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
426
436
  error: null,
427
437
  priority,
428
438
  };
429
- await appendAttemptEvent(run.db, registry, deliveryAttemptId, queuedEntry);
439
+ await appendAttemptEvent(
440
+ run.db,
441
+ registry,
442
+ deliveryAttemptId,
443
+ withIdempotencyKey(run, queuedEntry),
444
+ );
430
445
  await run.jobDispatcher.dispatch(
431
446
  channel.render ? DeliveryJobs.render : DeliveryJobs.send,
432
447
  {
@@ -439,6 +454,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
439
454
  priority,
440
455
  message,
441
456
  ...(run.jobIdempotencyKey !== undefined && { idempotencyKey: run.jobIdempotencyKey }),
457
+ ...(run.idempotencyKey !== undefined && { notifyIdempotencyKey: run.idempotencyKey }),
442
458
  },
443
459
  { priority: deliveryPriorityRank[priority] },
444
460
  );
@@ -605,6 +621,9 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
605
621
 
606
622
  const recipientChannelKey = (userId: string, channelName: string) => `${userId}|${channelName}`;
607
623
 
624
+ const isChannelSelected = (run: NotifyRun, channelName: string) =>
625
+ run.channelNames === undefined || run.channelNames.has(channelName);
626
+
608
627
  type ChannelGate = "open" | "channel_disabled" | "preference_disabled" | "rate_limited";
609
628
  type PrefetchedRecipients = {
610
629
  readonly addresses: ReadonlyMap<string, string | null>;
@@ -660,10 +679,11 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
660
679
  secrets,
661
680
  tenantConfigFor?.(tenantId),
662
681
  run.filesForTenant,
682
+ run.idempotencyKey,
663
683
  );
664
684
  for (const userId of userIds) {
665
685
  for (const channel of channels) {
666
- if (!channel.resolve) continue;
686
+ if (!channel.resolve || !isChannelSelected(run, channel.name)) continue;
667
687
  const key = recipientChannelKey(userId, channel.name);
668
688
  try {
669
689
  const gate = await evaluateChannelGate(
@@ -754,11 +774,12 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
754
774
  secrets,
755
775
  tenantConfigFor?.(tenantId),
756
776
  run.filesForTenant,
777
+ run.idempotencyKey,
757
778
  );
758
779
 
759
780
  for (const channel of channels) {
760
781
  // Route-only channel (no per-user address): not a user-notification target.
761
- if (!channel.resolve) continue;
782
+ if (!channel.resolve || !isChannelSelected(run, channel.name)) continue;
762
783
 
763
784
  const message = buildMessage(notificationType, data, channel.name, run.locale);
764
785
 
@@ -880,6 +901,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
880
901
  secrets,
881
902
  tenantConfigFor?.(tenantId),
882
903
  run.filesForTenant,
904
+ run.idempotencyKey,
883
905
  );
884
906
  const suppressed = await loadSuppressedAddresses(
885
907
  run,
@@ -1050,7 +1072,9 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
1050
1072
  deliveries: [],
1051
1073
  jobDispatcher: options.immediate ? undefined : (jobDispatcher ?? jobRunner),
1052
1074
  locale: options.locale,
1075
+ channelNames: options.channels === undefined ? undefined : new Set(options.channels),
1053
1076
  jobIdempotencyKey: jobIdempotencyKeyFor(idempotencyKey, route),
1077
+ idempotencyKey,
1054
1078
  filesForTenant:
1055
1079
  fileProviderResolver === undefined
1056
1080
  ? filesForTenant
@@ -33,6 +33,8 @@ export const deliveryAttemptSchema = z.object({
33
33
  priority: z.enum(["critical", "normal", "low"]),
34
34
  // Provider accepted the request but does not confirm delivery (e.g. Teams 202).
35
35
  confirmed: z.literal(false).optional(),
36
+ // The notify() idempotencyKey, so callers can find their attempts again; set on the first event of an attempt only.
37
+ idempotencyKey: z.string().optional(),
36
38
  });
37
39
 
38
40
  export type DeliveryAttemptPayload = z.infer<typeof deliveryAttemptSchema>;