@web-ts-toolkit/email-service 0.72.0 → 0.74.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.
package/README.md CHANGED
@@ -4,24 +4,151 @@ Typed email preparation, queue admission and bounded submission for Node.js 24 o
4
4
  content for SMTP or validate SendGrid dynamic-template data. Preparation alone does not enqueue, and admission never
5
5
  sends mail.
6
6
 
7
- ## Imports
7
+ ## Quickstart: enqueue and inspect a synthetic submission
8
8
 
9
9
  Install with `pnpm add @web-ts-toolkit/email-service`. Use named imports (or destructure `require()` in CommonJS).
10
- There is no default export. Preparation, admission, and the memory store need neither optional peer.
10
+ There is no default export. This standalone example uses no optional peers, credentials, or network. Save it as
11
+ `receipt.mts` and run `node receipt.mts`, or compile it as an ES module with TypeScript's `NodeNext` settings.
12
+ The provider is a test double for this one-recipient template: it **fabricates acceptance** and never sends mail.
11
13
 
12
- <!-- example: errors -->
14
+ <!-- example: quickstart -->
13
15
 
14
16
  ```typescript
15
- import { EmailError, type EmailErrorCode } from '@web-ts-toolkit/email-service';
17
+ import {
18
+ createEmailAdmin,
19
+ createEmailService,
20
+ createEmailTemplateRegistry,
21
+ createEmailWorker,
22
+ createMemoryEmailStore,
23
+ defineLocalTemplate,
24
+ type EmailProvider,
25
+ type SmtpSnapshot,
26
+ } from '@web-ts-toolkit/email-service';
27
+
28
+ const receipt = defineLocalTemplate({
29
+ kind: 'handlebars',
30
+ revision: 'v1',
31
+ defaults: { from: { address: 'sender@example.invalid' } },
32
+ subject: { kind: 'inline', content: 'Payment received' },
33
+ text: { kind: 'inline', content: 'Thank you for your payment.' },
34
+ parseInput(value) {
35
+ if (value !== null) throw new Error('Expected null');
36
+ return value;
37
+ },
38
+ parseData: () => ({}),
39
+ prepare: () => ({ to: [{ address: 'buyer@example.invalid' }], values: {} }),
40
+ });
41
+ const registry = createEmailTemplateRegistry({ receipt });
42
+ const store = createMemoryEmailStore();
43
+ await store.ready();
44
+
45
+ const queue = { scope: 'example-app', store };
46
+ const service = createEmailService({ ...queue, registry });
47
+ const ref = { kind: 'smtp', key: 'receipt-test', mode: 'live' } as const;
48
+ const eventId = 'order-paid-6042'; // A stable, opaque ID from the host's business event, not a new ID on retry.
49
+ const admission = await service.enqueue({
50
+ templateKey: 'receipt',
51
+ input: null,
52
+ key: { kind: 'single', idempotencyKey: `receipt-${eventId}` },
53
+ intent: { purpose: 'receipt', eventId },
54
+ provider: ref,
55
+ });
16
56
 
17
- const error = new EmailError('write_unconfirmed');
18
- const code: EmailErrorCode = error.code;
19
- // An unconfirmed write may have committed. Do not treat it as a definite failure.
20
- console.log(code);
57
+ const syntheticSmtp: EmailProvider<SmtpSnapshot> = {
58
+ ref, // Match the frozen kind, key and mode exactly.
59
+ prepare() {
60
+ return {
61
+ async submit({ signal }) {
62
+ signal.throwIfAborted();
63
+ return {
64
+ outcome: 'accepted',
65
+ retry: 'never',
66
+ stage: 'data',
67
+ reason: 'smtp_accepted',
68
+ recipients: [{ group: 'to', index: 0, status: 'accepted' }],
69
+ };
70
+ },
71
+ };
72
+ },
73
+ };
74
+ const worker = createEmailWorker({ ...queue, providers: [syntheticSmtp] });
75
+ try {
76
+ const report = await worker.run({ limit: 1 });
77
+ const job = await createEmailAdmin(queue).getJob(admission.job.jobId);
78
+ console.log(JSON.stringify({ admission: admission.status, submitted: report.counts.submitted, job }));
79
+ } finally {
80
+ const shutdown = await worker.shutdown();
81
+ if (shutdown.status !== 'stopped') throw new Error('Worker shutdown deadline elapsed');
82
+ }
21
83
  ```
22
84
 
23
- Compare `.code`, not class identity, if your application loads both builds.
24
- `PreparedEmailCommand` describes the sensitive, versioned outbox payload. Treat it like queue data, not a log record.
85
+ Expect `enqueued`, one synthetic submission and a redacted job with `latestAttempt.outcome: 'accepted'`.
86
+ With a real provider, acceptance confirms submission to that provider, not inbox delivery. SendGrid sandbox
87
+ validation is not submission.
88
+
89
+ The host owns business rules, scheduling and authorization. Use `createEmailService` or
90
+ [`createEmailBatchAdmission`](#enqueue-and-resume-a-batch) in producers, [`createEmailRelay`](#stage-a-host-owned-outbox)
91
+ for prepared outboxes, `createEmailWorker` for delivery, and `createEmailAdmin` for operations. They can run in
92
+ separate processes using the same backing queue and authorized scope, with the same binding when
93
+ [opting into SMTP capacity](#opt-in-to-larger-smtp-envelopes).
94
+
95
+ ## Support and limits
96
+
97
+ <!-- prettier-ignore -->
98
+ | Choose | Entrypoint / optional peer | Support and limits |
99
+ | --- | --- | --- |
100
+ | Local Handlebars → SMTP | Root `defineLocalTemplate`; `/smtp` `createSmtpProvider` needs Nodemailer `>=10.6.0 <11` at runtime | Verified TLS, live only. 50 total To/Cc/Bcc by default; [opt in](#opt-in-to-larger-smtp-envelopes) for 51–1,000. |
101
+ | Hosted SendGrid → HTTPS | Root `defineSendGridTemplate`; `/sendgrid` `createSendGridProvider`, no SDK or peer | Mail Send live or sandbox, V1 queue only. Freezes the template ID and data, not the active remote template version. |
102
+ | Memory queue | Root `createMemoryEmailStore`, no optional peer | Single instance, one process, non-durable. V1 defaults to 256 total jobs across scopes; no eviction to make room. |
103
+ | Durable MongoDB queue | `/mongoose` `createMongooseEmailStore`, caller-owned Mongoose `>=9.12.2 <10` connection | Writable MongoDB 8.x WiredTiger replica set with journaled majority; [topology and catalog privileges](#durable-store-with-mongoose) and private collection read/write access. |
104
+ | Custom provider | Root `EmailProvider` | Supported protocols only. No I/O in `prepare`; one-shot, deadline- and abort-aware `submit` with [normalized evidence](#implement-a-custom-provider), not raw replies. |
105
+ | Custom store | Root `EmailStore` | Scoped, bounded, atomic operations on store time. Enforce durable handoff and lease fencing, write confirmation, projection and retention; see [V1 transaction primitives][store-v1]. |
106
+
107
+ Always `await store.ready()` before use. Default V1 memory still allows legacy callers to skip it; SMTP-capacity
108
+ memory and MongoDB require it. Do not substitute memory when a durable store is unavailable.
109
+
110
+ The [V1 Store contract][store-v1] and [SMTP opt-in compatibility contract][store-smtp] are pinned historical
111
+ baselines. Use the installed declarations and this README for the current contract: the
112
+ [`StoreClaimNext` expiry signal](#run-a-worker) and [new-only SMTP attachment check](#configure-an-smtp-profile)
113
+ override the historical claim and insert rules. For opt-in stores also enforce the
114
+ [exact `StoreCall.smtpCapacity` binding and smaller bounds](#storage-rollout-and-rollback). For the public API,
115
+ the current peer ranges above and the template and provider typing, producer-only APIs and nonempty worker
116
+ requirements below supersede the corresponding historical examples.
117
+
118
+ [store-v1]: https://github.com/egose/web-ts-toolkit/blob/39848121d8b5746960078cac83949caaf26a9d9c/docs/task-artifacts/email-service/20261118-223259-email-service-package/v1-contract.md#store-adapter-transaction-primitives
119
+ [store-smtp]: https://github.com/egose/web-ts-toolkit/blob/39848121d8b5746960078cac83949caaf26a9d9c/docs/task-artifacts/email-service/20261120-214514-email-service-smtp-capacity/implementation-contract.md#factory-and-request-boundary
120
+
121
+ ## Handle errors by code
122
+
123
+ Check a known `.code` on a caught `unknown`, not `instanceof EmailError`. A subpath can throw a different
124
+ class than the root even within the same module format (all ESM or all CommonJS).
125
+
126
+ <!-- example: errors -->
127
+
128
+ ```typescript
129
+ import type { EmailErrorCode } from '@web-ts-toolkit/email-service';
130
+ import { createSendGridProvider, type SendGridProviderOptions } from '@web-ts-toolkit/email-service/sendgrid';
131
+
132
+ function hasEmailCode(error: unknown, code: EmailErrorCode): boolean {
133
+ if (typeof error !== 'object' || error === null) return false;
134
+ try {
135
+ return Object.getOwnPropertyDescriptor(error, 'code')?.value === code; // Read only an own data property.
136
+ } catch {
137
+ return false; // A thrown proxy can reject property inspection.
138
+ }
139
+ }
140
+
141
+ function configureSendGrid(options: SendGridProviderOptions) {
142
+ try {
143
+ return createSendGridProvider(options);
144
+ } catch (error: unknown) {
145
+ if (hasEmailCode(error, 'invalid_config')) {
146
+ return null; // Report a configuration failure without logging the options or the exception.
147
+ }
148
+ throw error; // Unexpected failure; do not assume it is a retryable package error.
149
+ }
150
+ }
151
+ ```
25
152
 
26
153
  ## Prepare a local template
27
154
 
@@ -30,7 +157,7 @@ Render an SMTP snapshot without Nodemailer, a store, or a network connection:
30
157
  <!-- example: local -->
31
158
 
32
159
  ```typescript
33
- import { createEmailTemplateRegistry, defineLocalTemplate } from '@web-ts-toolkit/email-service';
160
+ import { createEmailTemplateRegistry, defineLocalTemplate, type TemplateMap } from '@web-ts-toolkit/email-service';
34
161
 
35
162
  const welcome = defineLocalTemplate({
36
163
  kind: 'handlebars',
@@ -43,7 +170,7 @@ const welcome = defineLocalTemplate({
43
170
  return input;
44
171
  },
45
172
  prepare(name) {
46
- return { to: [{ address: 'recipient@example.invalid' }], values: { name } };
173
+ return { to: [{ address: 'recipient@example.invalid' }], values: { name: name.trim() } };
47
174
  },
48
175
  parseData(data) {
49
176
  if (!data || typeof data !== 'object' || !('name' in data) || typeof data.name !== 'string') {
@@ -53,10 +180,11 @@ const welcome = defineLocalTemplate({
53
180
  },
54
181
  });
55
182
 
56
- const registry = createEmailTemplateRegistry({ welcome });
183
+ const templates = { welcome } satisfies TemplateMap;
184
+ const registry = createEmailTemplateRegistry(templates);
57
185
  const welcomeCommand = {
58
186
  templateKey: 'welcome',
59
- input: '<Example>',
187
+ input: ' <Example> ',
60
188
  intent: { name: '<Example>' },
61
189
  key: { kind: 'single', idempotencyKey: 'welcome-1' },
62
190
  provider: { kind: 'smtp', key: 'standard-smtp', mode: 'live' },
@@ -66,7 +194,15 @@ const prepared = await registry.prepare('example-app', welcomeCommand);
66
194
 
67
195
  The snapshot has a plain-text subject and escaped HTML. `prepare` does not admit a job.
68
196
 
69
- Keep `parseInput` and `parseData` synchronous. Preparation can be async and may run again after a crash; keep
197
+ Use `satisfies TemplateMap` instead of annotating the definitions as `TemplateMap`. This keeps literal keys and their
198
+ input and provider types for the registry, service and batch. A widened `TemplateCommand<TemplateMap>` accepts either
199
+ provider, but cannot check keys or inputs against a specific registry.
200
+
201
+ `parseInput` synchronously validates the command's declared input shape at runtime. Its return type is the type callers
202
+ must supply as `command.input`. Normalize prepared values in `prepare` (here, `name.trim()`), rather than using
203
+ `parseInput` to convert from a different raw input shape.
204
+
205
+ Keep `parseData` synchronous too. Preparation can be async and may run again after a crash; keep
70
206
  side effects idempotent. `intent` is explicit, stable business meaning, not the generated message. Configure only
71
207
  trusted sources and helpers. HTML values escape by default; this is not sanitization. To update advertised local
72
208
  content, change its revision and create a new registry; `registry.invalidate(key?)` only refreshes the local cache.
@@ -142,42 +278,98 @@ console.log(first.job.jobId === again.job.jobId); // true
142
278
  insert and any confirmation share that budget. `retry` and `retention` are optional policy overrides frozen on the
143
279
  first insert; replay does not change them. Never put personal data or secrets into IDs or correlation tokens.
144
280
 
145
- ### Stage a host-owned outbox
281
+ ### Schedule a seven-day reminder
146
282
 
147
- Prepare before the business write. Pass `stagedReminder` from the SendGrid example as `email`. Your `commit`
148
- implementation saves the business change and the versioned, sensitive `email` value in **one host transaction**.
149
- Only after commit does your relay read that value and enqueue it on the caller-ready queue store:
283
+ `scheduleAt` is the earliest eligible time, not a timer. Both it and `expiresAt` are Unix milliseconds.
284
+ Expiry defaults to **24 hours from preparation**, so a seven-day schedule needs an explicit later expiry.
285
+ Set `expiresAt` in `prepare`: it must be strictly after preparation and `scheduleAt`, and at most **30 days
286
+ from preparation**. This example reuses `reminder` from the SendGrid template example and a caller-ready V1
287
+ store. It admits a sandbox reminder when the booking is recorded, without starting a worker:
150
288
 
151
- <!-- example: outbox -->
289
+ <!-- example: scheduled-reminder -->
152
290
 
153
291
  ```typescript
154
292
  import {
155
293
  createEmailService,
156
294
  createEmailTemplateRegistry,
295
+ defineSendGridTemplate,
157
296
  type EmailStore,
158
- type PreparedEmailCommand,
159
297
  } from '@web-ts-toolkit/email-service';
160
298
 
299
+ const dayMs = 86_400_000;
300
+ const sevenDayReminder = defineSendGridTemplate({
301
+ ...reminder,
302
+ async prepare(hours, context) {
303
+ return { ...(await reminder.prepare(hours, context)), expiresAt: context.now + 8 * dayMs };
304
+ },
305
+ });
306
+ const scheduledRegistry = createEmailTemplateRegistry({ reminder: sevenDayReminder });
307
+
308
+ function enqueueSevenDayReminder(store: EmailStore, booking: { eventId: string; recordedAt: number }) {
309
+ const service = createEmailService({ scope: 'example-app', store, registry: scheduledRegistry });
310
+ return service.enqueue({
311
+ templateKey: 'reminder',
312
+ input: 7 * 24,
313
+ key: { kind: 'single', idempotencyKey: `seven-day-reminder-${booking.eventId}` },
314
+ intent: { purpose: 'booking-reminder', eventId: booking.eventId, daysAfterBooking: 7 },
315
+ scheduleAt: booking.recordedAt + 7 * dayMs,
316
+ provider: { kind: 'sendgrid', key: 'validation', mode: 'sandbox' },
317
+ });
318
+ }
319
+ ```
320
+
321
+ Pass the original event ID and timestamp on replay, not a fresh `Date.now()`; the schedule is part of the
322
+ fingerprint. `PrepareContext` provides `now`, not `scheduleAt`; if your expiry depends on a variable schedule,
323
+ pass the needed timestamp in your validated input. The expiry is frozen in the prepared snapshot: relay,
324
+ same-key replay, worker retries, and redrive do not extend it. Expiry prevents a new launch; it cannot recall
325
+ one already in progress.
326
+
327
+ ### Stage a host-owned outbox
328
+
329
+ Prepare before the business write. Pass `stagedReminder` from the SendGrid example as `email`. Your `commit`
330
+ implementation saves the business change and the versioned, sensitive `email` value in **one host transaction**.
331
+ Only after commit does your relay read that value and enqueue it on the caller-ready queue store. The relay process
332
+ does not need a template registry, worker, or delivery credentials. Treat `PreparedEmailCommand` like queue data,
333
+ not a log record:
334
+
335
+ <!-- example: outbox -->
336
+
337
+ ```typescript
338
+ import { createEmailRelay, type EmailRelayOptions, type PreparedEmailCommand } from '@web-ts-toolkit/email-service';
339
+
161
340
  type CommitReminder = (row: { reminderId: string; email: PreparedEmailCommand }) => Promise<void>;
162
341
 
163
342
  async function writeReminder(reminderId: string, email: PreparedEmailCommand, commit: CommitReminder) {
164
343
  await commit({ reminderId, email });
165
344
  }
166
345
 
167
- function relayReminder(store: EmailStore, email: PreparedEmailCommand) {
168
- const relay = createEmailService({ scope: 'example-app', store, registry: createEmailTemplateRegistry({}) });
169
- return relay.enqueuePrepared(email);
346
+ function makeReminderRelay(store: EmailRelayOptions['store']) {
347
+ const relay = createEmailRelay({ scope: 'example-app', store });
348
+ return (row: { email: PreparedEmailCommand }) => relay.enqueuePrepared(row.email);
170
349
  }
171
350
  ```
172
351
 
173
- Relay validates the V1 DTO, its hashes, and its scope. It does not join your transaction, rerender, refresh expiry,
174
- or send. Mark your outbox row relayed only after `enqueued` or `replayed`. If an acknowledgement is lost, relay the
175
- same persisted snapshot under the same scoped key; do not prepare a replacement. Keep the relay within the
176
- idempotency window. Restrict access to the staged payload; the returned job summary contains neither bodies nor addresses.
352
+ Create the relay once and call the returned function for each committed outbox row. It validates the snapshot,
353
+ hashes, scope and binding before looking up the key. A retained match replays even after snapshot expiry; an
354
+ expired snapshot for a new job is rejected. Relay does not join your transaction, rerender, refresh expiry, or
355
+ send. `createEmailService` also exposes the same `enqueuePrepared` method if your process already has a registry.
356
+
357
+ Older staged SMTP snapshots with `message/*` or `multipart/*` attachments still replay a retained match, but fail
358
+ with `invalid_snapshot` on a new admission. Treat this as an outbox validation error, not a transient send failure
359
+ or proof that an earlier uncertain write did not commit. Resolve any uncertain admission under the original key.
360
+ For an unadmitted entry, use your outbox recovery process to fix the attachment format and stage it again.
361
+ Previously admitted rows stay readable but the bundled SMTP adapter still rejects those attachments. Replay
362
+ neither changes their snapshots nor reopens terminal jobs for delivery.
363
+
364
+ Mark your outbox row relayed only after `enqueued` or `replayed`. If an acknowledgement is lost, relay the same
365
+ persisted snapshot under its original scoped key and queue binding; do not prepare a replacement. Keep the relay
366
+ within the idempotency window. Restrict access to the staged payload; the returned job summary contains neither
367
+ bodies nor addresses.
177
368
 
178
369
  ## Configure an SMTP profile
179
370
 
180
- Install `nodemailer@">=10.6.0 <11"` to import the SMTP runtime entry. Its profile `key` must match the prepared snapshot.
371
+ Install the [optional Nodemailer peer](#support-and-limits) to import the SMTP runtime entry. Its profile `key`
372
+ must match the prepared snapshot.
181
373
 
182
374
  <!-- example: smtp-profile -->
183
375
 
@@ -195,11 +387,16 @@ const smtp = createSmtpProvider({
195
387
  and verify the certificate against `servername` (if specified) or `host`, including IP SAN verification for literal
196
388
  IPs. `ca` accepts one PEM CA certificate per array entry and replaces Node's default trust roots. `auth: { user, pass }`
197
389
  uses advertised ESMTP PLAIN or LOGIN only over verified TLS; there is no plaintext fallback.
390
+ - The client greeting is fixed: `EHLO email.invalid` before and after the required STARTTLS upgrade, or once over
391
+ implicit TLS. `servername` is for remote TLS SNI and certificate verification; it does not change EHLO.
392
+ Relays requiring a different EHLO name are not supported.
198
393
  - Use an ASCII DNS host or a literal IP. The adapter uses a cancellable DNS resolver (not OS hosts-file aliases) and
199
394
  dials one address. It does not pool, retry or select another server after a failure.
200
395
  - `prepare` validates and copies the snapshot and attachment bytes without network I/O. SMTP sends visible To/Cc,
201
- envelope-only Bcc and no implicit path or URL inputs. Attachments are ordinary MIME leaf parts, not nested message
202
- or multipart MIME structures.
396
+ envelope-only Bcc and no implicit path or URL inputs. Attachments are ordinary MIME leaf parts.
397
+ Both SMTP queue modes reject `message/*` and `multipart/*` refs with `invalid_snapshot` during new registry
398
+ preparation or admission, before they can be persisted or resolved by a worker. Direct SMTP preparation still
399
+ refuses these types. SendGrid behavior is unchanged.
203
400
  - `submit({ signal, timeoutMs })` consumes the prepared submission on a valid call. It closes its connection on abort
204
401
  or timeout and never waits indefinitely for a peer. Neither closing the connection nor an `unknown` result means
205
402
  the relay discarded the message. `accepted` and `partially_accepted` require a final DATA acknowledgement and mean
@@ -248,16 +445,21 @@ await memoryStore.ready();
248
445
  ```
249
446
 
250
447
  Share the same instance to exercise competing callers. Each instance loses its state on restart and does not share
251
- state across processes. Capacity (default 256 jobs) is shared across scopes; a full store rejects new jobs instead of
252
- evicting retained ones. This is not a fallback for durable persistence. The `EmailStore` methods are private lifecycle
253
- primitives for adapters and tests, not application-facing routes. Claims include sensitive snapshots and ownership
254
- tokens; do not log or expose them. Store operations alone never contact a provider.
448
+ state across processes. The `EmailStore` methods are private lifecycle primitives for adapters and tests, not
449
+ application-facing routes. Claims include sensitive snapshots and ownership tokens; do not log or expose them.
450
+ Store operations alone never contact a provider.
255
451
 
256
452
  ## Run a worker
257
453
 
258
- Bind a caller-ready store to the same scope as the admission service. Pass the configured provider instances, not
454
+ Bind a caller-ready store to the same scope as the admission service. Pass at least one configured provider, not
259
455
  credentials in a queue payload. The profile's key, kind and mode must match the frozen snapshot.
260
456
 
457
+ **Migrating an empty V1 worker:** `providers: []` now throws `invalid_config` at construction, as it already did
458
+ with `smtpCapacity`. No queue or provider work starts. If you only enqueue batches, replace the empty worker and
459
+ combined facade with [`createEmailBatchAdmission({ service })`](#enqueue-and-resume-a-batch) (pass `smtpCapacity`
460
+ if configured). For already prepared commands, [`createEmailRelay`](#stage-a-host-owned-outbox) needs no worker
461
+ or template registry.
462
+
261
463
  <!-- example: worker -->
262
464
 
263
465
  ```typescript
@@ -278,40 +480,143 @@ function runDue(worker: EmailWorker, signal: AbortSignal) {
278
480
  ```
279
481
 
280
482
  - Your host calls `await runDue(worker, signal)` to do a bounded run.
281
- Those are the default work limits; set lower limits when appropriate. `timeoutMs` defaults to 30 seconds for the
483
+ Those are the V1 default work limits; set lower limits when appropriate. `timeoutMs` defaults to 30 seconds for the
282
484
  whole run, with a separate bounded finish grace. There is no polling or automatic connection management.
283
485
  One run per instance is allowed. Different instances can share a queue. `idle` is not a whole-queue inventory.
486
+ - On `report.stop === 'expiry_maintenance_required'`, the entire bounded claim window was filled with expired
487
+ queued jobs. There may be live work behind them. Schedule another run for the **same scope** with a positive
488
+ `maintenanceLimit` (or omit it for the default: 10 in V1, 4 with `smtpCapacity`). Keep scheduling bounded runs
489
+ if the backlog takes more than one sweep. `maintenanceLimit: 0` skips both recovery and queued expiry; repeatedly
490
+ running with zero maintenance won't clear the expired prefix. A follow-up run can submit eligible mail as usual.
491
+ - This stop is new for both bundled queues. Handle it in exhaustive switches on `EmailRunReport.stop` (including
492
+ `batch.run()`); direct `EmailStore.claimNext()` consumers can use `StoreClaimNext` and call bounded `expireNext()`
493
+ in the same scope before retrying. Existing custom stores can keep returning the previous `StoreNext` statuses.
494
+ Pair updated bundled stores with updated workers when passing store objects in-process: older workers report
495
+ the new result as a store error. There is no persisted-data or Mongo catalog migration.
284
496
  - The worker prepares the provider payload, validates attachment bytes through your `attachmentResolvers`, and asks
285
497
  the optional `rateLimiter` for one permit before making a durable handoff. A worker limiter should be instantiated
286
498
  per worker; a shared limiter must enforce the actual shared quota outside the worker. The worker does not wait for
287
499
  a deferred permit, refund permits, rerender snapshots, or choose an alternate profile.
288
- - A missing or late handoff acknowledgement never permits a send. A finish write error is not evidence of rejection.
289
- `unconfirmed` means the worker could not prove the stored attempt outcome; `unknown` is a stored result that is
290
- never automatically retried. `submitted` counts full and partial acceptance, not sandbox validation or inbox
291
- delivery. An application that explicitly redrives unknown work must accept possible duplicates.
500
+ - `retry.maxAttempts` defaults to **3 claims**, not three provider calls. Three rate deferrals can end in
501
+ `attempts_exhausted` with zero provider calls. For safe transient results with claims left, the retry time is the
502
+ later of jittered exponential backoff (default base 1 s, cap 60 s) and any valid limiter or provider retry floor.
503
+ No retry is scheduled at or after expiry. Pace worker runs for your quota; there is no separate deferral budget.
504
+ - A missing or late handoff acknowledgement never permits a send. A finish write error is not proof of rejection.
505
+ `submitted` counts full and partial acceptance, not sandbox validation. Neither partial nor unknown outcomes
506
+ automatically resend; see [recovery](#recover-unresolved-submissions).
292
507
  - `await worker.shutdown({ timeoutMs: 15_000 })` permanently closes the worker, not the store. `stopped` means no
293
508
  run or provider I/O is active; `pendingCallbacks` counts host promises still held after cancellation. Injected
294
509
  stores and providers must honor call deadlines, abort actual I/O and wait for it to settle. A timed-out shutdown
295
510
  can be awaited again, and it does not recall bytes already sent.
296
511
 
512
+ ### Roll out a provider profile in a shared scope
513
+
514
+ Workers on the same queue and scope compete for eligible jobs. Claims do not filter by profile, even when every
515
+ worker has providers configured. Each worker needs an exact match for every active provider reference (kind, key
516
+ and mode) and an `attachmentResolvers` entry for every `resolverKey` its jobs can reference. Startup checks only
517
+ the local configuration; the host must verify that all workers on the route have what they need.
518
+
519
+ For example, workers A and B share the `example-app` scope on one queue. Existing jobs use a live `smtp` profile
520
+ with key `standard-smtp` and may reference the `files-v1` resolver. New jobs will use a live `smtp` profile with
521
+ key `next-smtp` and the `files-v2` resolver. Use a distinct profile key so the two profiles can coexist.
522
+
523
+ 1. Replace worker A with one configured for **both** profiles and resolvers. B still has only the old
524
+ configuration, so producers must continue using `standard-smtp` and `files-v1`.
525
+ 2. Replace worker B with the same dual configuration. Confirm that no worker still claiming in `example-app`
526
+ lacks either profile or resolver.
527
+ 3. Only now switch producers of new work to `next-smtp` and `files-v2`. Keep both routes on both workers while the
528
+ old work drains, including access to its referenced attachment versions.
529
+ 4. Remove `standard-smtp` and `files-v1` only after nothing still needs them. Account for scheduled jobs, retries,
530
+ in-flight claims, staged outbox entries that can still be relayed, and any eligible `unknown` jobs you intend to
531
+ explicitly redrive. A run reporting `idle` does not prove the old work has drained.
532
+
533
+ If the fleets cannot share configuration, keep one on `example-app` and route the other to `example-app-next` in
534
+ the same store, or use separate backing queues. Bind each fleet's producers, relays and workers to the matching
535
+ scope and queue. Leave already staged and admitted work on its original route.
536
+
537
+ A missing or mismatched profile is a terminal pre-handoff failure: `failed` with reason `profile_unavailable`
538
+ and no provider submission on that attempt. The worker does not retry the job or switch profiles. After you
539
+ fix the configuration, replaying the same scoped command under the same key returns `replayed` with the existing
540
+ failed job while its identity is retained; it does not reopen the job. Changing the command's provider reference
541
+ under that key results in `idempotency_conflict`.
542
+
543
+ ### Implement a custom provider
544
+
545
+ Use `EmailProvider<SmtpSnapshot>` or `EmailProvider<SendGridSnapshot>` to implement one of the supported
546
+ protocols. Keep `prepare` synchronous and free of I/O. This SMTP test double matches the `standard-smtp` profile
547
+ from the local template example. Use it only with an isolated test queue: it records synthetic acceptance and
548
+ sends nothing.
549
+
550
+ <!-- example: custom-provider -->
551
+
552
+ ```typescript
553
+ import {
554
+ createSmtpAcceptanceResult,
555
+ EmailError,
556
+ type EmailProvider,
557
+ type ProviderResult,
558
+ type SmtpSnapshot,
559
+ } from '@web-ts-toolkit/email-service';
560
+
561
+ const syntheticSmtp: EmailProvider<SmtpSnapshot> = {
562
+ ref: { kind: 'smtp', key: 'standard-smtp', mode: 'live' },
563
+ prepare({ snapshot: { envelope } }) {
564
+ const recipients = (['to', 'cc', 'bcc'] as const).flatMap((group) =>
565
+ envelope[group].map((_, index) => ({ group, index, status: 'accepted' as const })),
566
+ );
567
+ let submitted = false;
568
+ return {
569
+ async submit({ signal }): Promise<ProviderResult> {
570
+ if (submitted) throw new EmailError('closed');
571
+ submitted = true;
572
+ if (signal.aborted) {
573
+ return { outcome: 'unknown', retry: 'never', stage: 'connect', reason: 'provider_aborted' };
574
+ }
575
+ return createSmtpAcceptanceResult(recipients);
576
+ },
577
+ };
578
+ },
579
+ };
580
+ ```
581
+
582
+ For the test queue above, pass `[syntheticSmtp]` to `makeWorker(store, profiles)` in place of a real SMTP adapter.
583
+ A real `submit` must be one-shot, honor `signal` and `timeoutMs`, and settle only once it cannot perform more
584
+ send I/O. Report SMTP acceptance or partial acceptance only after the final DATA acknowledgement, with one
585
+ entry per envelope recipient (group and zero-based index; use To/Cc/Bcc order with `smtpCapacity`). If you
586
+ cannot establish what happened, report `unknown`, not a safe retry.
587
+
588
+ **Migrating custom TypeScript providers:** `ProviderResult` now ties `outcome`, `retry`, `stage`, and metadata to
589
+ `reason`. Return a complete result in each branch rather than assembling those fields independently or casting
590
+ from `AttemptResult`. Annotate `submit` with `Promise<ProviderResult>` as above or use `satisfies ProviderResult`
591
+ on a result literal. A literal `smtp_accepted` result needs a nonempty tuple of accepted recipients. For a dynamic
592
+ list or any `smtp_partial` result, call `createSmtpAcceptanceResult(recipients, messageId?)` from the root
593
+ (no optional peer). It copies and freezes the evidence without reordering it, and returns `smtp_partial` only
594
+ when both statuses are present. Empty, all-rejected, or malformed evidence throws `invalid_command`; an
595
+ all-rejected list is not acceptance. Omit `messageId` unless it is `<${attemptId}@email.invalid>` for this attempt.
596
+ Only live `sendgrid_accepted` can include `providerMessageId`, and only `sendgrid_throttled` can include a
597
+ provider `retryHint` (`delayMs`, `notBefore`, or both). Sandbox success is `sendgrid_validated`, not
598
+ `sendgrid_accepted`.
599
+
600
+ This tightens the TypeScript contract without changing stored formats or submission semantics. The worker still
601
+ checks evidence against the actual envelope and profile mode. Invalid evidence after handoff becomes `unknown` with reason
602
+ `transport_uncertain`; it never authorizes an automatic resend.
603
+
297
604
  ## Enqueue and resume a batch
298
605
 
299
- Use `createEmailBatchService` with a service and worker bound to the **same scope and underlying store**.
300
- Each item is a template command without a standalone `key`. Using `welcomeCommand`, `service`, `store`, `smtp`
301
- and `makeWorker` from the preceding examples:
606
+ Use `createEmailBatchAdmission` in a producer process. It takes the bound admission `service` from the enqueue
607
+ example and only exposes `enqueueBatch`. No worker, delivery credentials, or optional peer is needed for the memory
608
+ example. Each item is a template command without a standalone `key`. Using `welcomeCommand` from above:
302
609
 
303
- <!-- example: batch -->
610
+ <!-- example: batch-admission -->
304
611
 
305
612
  ```typescript
306
- import { createEmailBatchService } from '@web-ts-toolkit/email-service';
613
+ import { createEmailBatchAdmission } from '@web-ts-toolkit/email-service';
307
614
 
308
615
  const { key: _singleKey, ...command } = welcomeCommand;
309
- const worker = makeWorker(store, [smtp]);
310
- const batch = createEmailBatchService({ service, worker });
616
+ const batch = createEmailBatchAdmission({ service });
311
617
  const request = { batchId: 'welcome-run-1', items: [{ itemId: 'notice-1', command }] };
312
618
  const admission = await batch.enqueueBatch(request);
313
619
  const resumed = await batch.enqueueBatch(request); // Same item identity; replays without preparing again.
314
- // When the host is ready to process due jobs, call batch.run({ limit: 10, concurrency: 2 }).
315
620
  ```
316
621
 
317
622
  - An enqueue call validates all 1–100 item envelopes and unique IDs before any lookup or preparation. It admits in
@@ -326,6 +631,37 @@ const resumed = await batch.enqueueBatch(request); // Same item identity; replay
326
631
  `enqueue`. It passes the remaining time within that API's 50–60,000 ms range and a signal that can stop work
327
632
  sooner. The batch waits for a started item to settle rather than assuming a write was cancelled. A custom
328
633
  service must honor these limits and settle its I/O; one that does not cooperate can keep the batch pending.
634
+
635
+ ### Combine batch admission and delivery
636
+
637
+ If the same process also runs delivery, `createEmailBatchService` adds the configured worker's `run` to the same
638
+ `enqueueBatch` operation. Build both components from the same backing configuration, using a single store instance
639
+ for memory or matching durable queue settings. Matching scope and capacity do not prove two stores share a backing.
640
+ This is an alternative to the producer example, using `registry`, `welcomeCommand` and `smtp` from above:
641
+
642
+ <!-- example: batch -->
643
+
644
+ ```typescript
645
+ import {
646
+ createEmailBatchService,
647
+ createEmailService,
648
+ createEmailWorker,
649
+ createMemoryEmailStore,
650
+ } from '@web-ts-toolkit/email-service';
651
+
652
+ const store = createMemoryEmailStore();
653
+ await store.ready();
654
+ const queue = { scope: 'example-app', store };
655
+ const service = createEmailService({ ...queue, registry });
656
+ const worker = createEmailWorker({ ...queue, providers: [smtp] });
657
+ const batch = createEmailBatchService({ service, worker });
658
+ const { key: _singleKey, ...command } = welcomeCommand;
659
+ const request = { batchId: 'welcome-run-1', items: [{ itemId: 'notice-1', command }] };
660
+ const admission = await batch.enqueueBatch(request);
661
+ const resumed = await batch.enqueueBatch(request);
662
+ // When the host is ready to process due jobs, call batch.run({ limit: 10, concurrency: 2 }).
663
+ ```
664
+
329
665
  - `batch.run` is the configured worker's **scope-wide** run, with the same bounds, limiter and report. It can
330
666
  process unrelated due jobs in that scope. It neither filters by batch ID nor rewrites envelopes; the local
331
667
  grouping ID is not SendGrid's `batch_id`.
@@ -353,30 +689,80 @@ async function inspectResults(store: EmailStore, jobId: string) {
353
689
  }
354
690
  ```
355
691
 
356
- - Authorize requests in your application; a scope or cursor is not authentication. Results contain only redacted
357
- metadata, fixed diagnostic codes, and reliably known recipient indexes, never queue snapshots, addresses, provider
358
- responses or ownership tokens. Activities are submission history, not inbox delivery receipts or inputs to a resend.
692
+ - Results contain redacted metadata, fixed diagnostic codes and reliably known recipient indexes, never queue
693
+ snapshots, addresses, raw responses or ownership tokens. Activities describe past attempts, not current holds.
359
694
  - Lists contain complete committed projections, including those pending acknowledgement on the job. They order
360
695
  newest finish first, then by job and attempt ID. `from` is inclusive; `before` is exclusive. Keep the same scope
361
- and filters when passing `nextCursor`; page size can change (default 25, range 1–100). Pages are not snapshots.
362
- - `reconcile` and `cleanup` do sequential work (default 20 steps, range 1–100); their counts describe only confirmed
363
- progress in that call. All admin methods accept `signal` and one whole-call `timeoutMs` (default 10 seconds,
364
- override 50–60,000 ms). A persistence failure can leave work committed; a later maintenance call safely resumes it.
365
- An optional `onActivity` runs after a new confirmed projection ACK, without waiting for its returned promise.
366
- If one callback is already pending, later notifications are skipped, not queued or retried.
367
- - `cancel(jobId)` cannot recall mail after handoff. `resolveUnknown({ jobId, attemptId, action: 'dismiss' })` closes
368
- the hold without changing the outcome. Explicit `'redrive'` with `acknowledgeDuplicateRisk: true` can requeue an
369
- eligible unknown job once for a future worker run. Quiesce suspected old workers and review provider evidence
370
- first: redrive can duplicate an accepted submission, and the admin never submits the message itself. After
371
- `write_unconfirmed`, read the current job or repeat the exact same action; do not assume it rolled back.
372
- - Retention is frozen at admission (default 7 days for payloads and 30 days each for history and idempotency).
373
- Cleanup holds unresolved unknowns and unacknowledged history, prunes settled payloads when eligible, and only
374
- removes the replay guard after all retention windows and the projection drain, once activities have been deleted.
696
+ and filters when passing `nextCursor` as `cursor`; page size can change (V1 default 25, range 1–100).
697
+ - `reconcile` and `cleanup` do sequential work (V1 default 20 steps, range 1–100); their counts describe only
698
+ confirmed progress in that call. All admin methods accept `signal` and one whole-call `timeoutMs` (default 10 seconds,
699
+ override 50–60,000 ms). A persistence failure can leave work committed; later bounded maintenance can resume it.
700
+ `onActivity` is best effort after a newly confirmed projection ACK: if one callback is pending, later
701
+ notifications are skipped, not queued or retried.
702
+
703
+ ### Recover unresolved submissions
704
+
705
+ Use the original caller-ready store, authorized scope and `smtpCapacity` binding (if enabled). The host
706
+ authorizes reads and actions; IDs and cursors are not credentials. There is no API that lists all current holds.
707
+
708
+ 1. **Record IDs.** Persist the original queue/scope, opaque host reference and `job.jobId` from `enqueued` or
709
+ `replayed` before acknowledging the host item or marking an outbox row relayed. For batches, save successful
710
+ jobs alongside their batch/item IDs. Resume uncertain admissions only within the replay window and on the
711
+ original route with the same key and intent (same staged command for a relay; same batch/item IDs and intents
712
+ for a batch). Don't replay completed commands to find an ID: after purge they can enqueue anew. Record scoped
713
+ job/attempt IDs (when present), operation, status and reason from worker `items`, including recovery and uncertainty. Keep `stop` and
714
+ `counts.persistenceFailures`: a lost claim ACK may have no item. Restrict access and omit private payloads.
715
+ 2. **Read current state.** `unconfirmed` means the worker could not confirm the stored outcome;
716
+ `write_unconfirmed` means a write may have committed. Neither proves rollback or non-submission. A `handed_off`
717
+ lease does not prove provider invocation, and `providerInvoked: false` on recovery says nothing about the old
718
+ owner. Read `admin.getJob(jobId)` even before projection. Act only on a terminal `unknown` with `unknownOpen: true`
719
+ and `latestAttempt.outcome === 'unknown'`. Take the ID from `latestAttempt` and match it to any candidate attempt
720
+ from a report or activity. On a changed attempt, failed read or `null`, do not act on stale evidence. A missing
721
+ job does not prove non-submission.
722
+ 3. **If IDs are missing, look for candidates, not a complete worklist.** Check host records first. Run bounded
723
+ `admin.reconcile({ limit: 4, timeoutMs: 10_000 })` passes before paging. They project attempts without recovering
724
+ leases or sending; back off on contention and surface failures. Set a fixed `finishedAt` window in Unix ms
725
+ (`from` inclusive, `before` exclusive), then page `admin.listActivities({ from, before, limit: 8 })`.
726
+ Use a shared deadline signal and cap passes, pages and reads (e.g. three pages and 24 `getJob` calls).
727
+ Filter for `activity.result.outcome === 'unknown'`, deduplicate by scoped job/attempt and recheck the exact
728
+ open attempt with `getJob`.
729
+ Save the route, filters and opaque cursor after accounting for a whole page; resume an interrupted page from
730
+ its start. Cursors mark positions, not snapshots or watermarks. Later projections can appear before your
731
+ bookmark and older holds outside the window; history can also be purged. Revisit overlapping or older
732
+ windows from the first page within budget. Idle reconciliation or an empty/final page cannot rule out holds
733
+ (e.g. unprojected attempts or leases); report gaps and escalate if you need a complete inventory.
734
+ 4. **Let a healthy worker recover an expired lease only if delivery is authorized.** If still leased, wait for
735
+ the owner or quiesce suspected old workers: stop scheduling and verify no runs or provider I/O remain
736
+ (`shutdown()` returns `stopped`, not `deadline`, or equivalent host confirmation). After store-time lease
737
+ expiry, run a bounded worker in the original scope with positive `maintenanceLimit`. Pre-handoff recovery
738
+ can safely retry within policy; post-handoff recovery records `unknown`. Even `limit: 1` can send unrelated
739
+ mail; there is no recovery-only admin run. Re-read the job and check authorized provider evidence for that
740
+ attempt. Missing provider logs do not prove rejection.
741
+ 5. **Resolve the exact open attempt, or leave it open.** Re-read immediately before acting.
742
+ `admin.resolveUnknown({ jobId, attemptId, action: 'dismiss' })` closes the hold without sending or changing
743
+ the outcome, even after expiry. Dismissal does not assert acceptance or rejection; cancellation cannot recall mail.
744
+ Do not redrive confirmed acceptance. Only after quiescing suspected old workers, reviewing evidence and
745
+ accepting the risk of duplicate submission should an authorized operator call
746
+ `admin.resolveUnknown({ jobId, attemptId, action: 'redrive', acknowledgeDuplicateRisk: true })`.
747
+ Redrive requires a retained snapshot, store time before the original `expiresAt`, and no previous redrive.
748
+ It requeues the same snapshot with **one extra claim**, not a send guarantee, automatic retry or expiry
749
+ extension. A future worker needs the matching profile and resolvers. A second unknown can only be dismissed;
750
+ never bypass the guards with a fresh key. Audit the actor and exact scoped decision. On `write_unconfirmed`,
751
+ read `job.resolutions` for the same attempt/action; if absent and still eligible, retry only that exact
752
+ authorized command within budget. `resolved` confirms a new decision; `replayed` confirms the prior decision
753
+ and returns the current job, which may have advanced. On `not_found`, `resolution_conflict` or `expired`,
754
+ stop and re-read.
755
+ 6. **Schedule projection and cleanup separately from delivery.** Open unknowns retain payload, history and
756
+ identity even after expiry. Frozen retention minimums (defaults: payload 7 days, history and idempotency
757
+ 30 days each) start at dismissal or a settled terminal result after redrive. All attempts need projection
758
+ ACKs before payload pruning. Schedule bounded `admin.cleanup({ limit: 4 })` calls: after the retention windows
759
+ and projection drain, cleanup deletes activities before purging the job and replay guard. It never clears an
760
+ open hold.
375
761
 
376
762
  ## Durable store with Mongoose
377
763
 
378
- Install `mongoose@">=9.12.2 <10"` alongside the package. Supply an open connection (not the global default)
379
- to a writable MongoDB 8.x WiredTiger replica set with journaled majority enabled.
764
+ Install the [optional Mongoose peer](#support-and-limits) and open a caller-owned connection
765
+ (not the global default) to the supported replica set:
380
766
 
381
767
  <!-- example: mongoose -->
382
768
 
@@ -391,7 +777,7 @@ async function openStore(replicaSetUri: string) {
391
777
  await connection.asPromise();
392
778
  const store = createMongooseEmailStore(connection);
393
779
  await store.ready();
394
- return { store, close: () => connection.close() };
780
+ return { connection, store, close: () => connection.close() };
395
781
  } catch (error) {
396
782
  await connection.close();
397
783
  throw error;
@@ -400,10 +786,10 @@ async function openStore(replicaSetUri: string) {
400
786
  ```
401
787
 
402
788
  - `ready()` must succeed before any store call. It checks server status, replica-set config and startup
403
- options, reads the collection/index catalog, and installs only missing V1 definitions. The principal needs
404
- `serverStatus`, `replSetGetConfig`, `getCmdLineOpts`, collection/index inspection and creation as applicable,
405
- and read/write access to the two private collections. Unsupported topology, validators, collations, model
406
- aliases and conflicting or extra indexes are not adopted or repaired.
789
+ options, reads the collection/index catalog, and installs only missing definitions for the selected format.
790
+ The principal needs `serverStatus`, `replSetGetConfig`, `getCmdLineOpts`, collection/index inspection and
791
+ creation as applicable, and read/write access to the two private collections. Unsupported topology, validators,
792
+ collations, model aliases and conflicting or extra indexes are not adopted or repaired.
407
793
  - `jobsCollection` and `activitiesCollection` default to `email_jobs` and `email_activities`.
408
794
  `jobsModelName` and `activitiesModelName` reserve connection-local names (defaults `EmailJobV1` and
409
795
  `EmailActivityV1`); no models are registered. Keep both collections private to this adapter: no manual
@@ -421,7 +807,148 @@ async function openStore(replicaSetUri: string) {
421
807
  result data; a provider accepting a submission would not establish inbox delivery. Host driver command
422
808
  monitoring can see private BSON; don't enable raw command logging in production.
423
809
 
424
- ## Integration entrypoints
810
+ ## Opt in to larger SMTP envelopes
811
+
812
+ Omit `smtpCapacity` for V1: **50 total To/Cc/Bcc recipients**, unchanged default SMTP and SendGrid live/sandbox
813
+ behavior, and the existing store definitions. The opt-in is for live SMTP only. It accepts one complete envelope
814
+ per message; it never splits or truncates the envelope. To/Cc stay visible; Bcc stays envelope-only.
815
+
816
+ Choose one **canonical lowercase UUIDv4** for the logical store and an integer `maxRecipients` from **51 to 1,000**.
817
+ Keep that binding in trusted host configuration and pass it as `smtpCapacity` to every factory in that queue:
818
+ registry, store, admission service, prepared relay, batch admission or combined batch service, each SMTP profile,
819
+ worker and admin. They compare the tuple by value and take frozen copies. Do not read it from request data or infer
820
+ it from a snapshot or a worker setting. Factory mismatches fail with `invalid_config`. There is no new environment
821
+ setting; the host still supplies SMTP credentials separately where delivery runs.
822
+
823
+ This example uses both optional peers and an already open [Mongoose connection](#durable-store-with-mongoose).
824
+ It prepares and relays a snapshot for 51 synthetic addresses without running the worker. In production,
825
+ [stage and commit the snapshot in the host outbox](#stage-a-host-owned-outbox) before relaying. Replace the
826
+ example UUID with one assigned to your store; do not generate a new UUID on startup.
827
+
828
+ <!-- example: smtp-capacity -->
829
+
830
+ ```typescript
831
+ import type { Connection } from 'mongoose';
832
+ import {
833
+ createEmailAdmin,
834
+ createEmailBatchAdmission,
835
+ createEmailBatchService,
836
+ createEmailRelay,
837
+ createEmailService,
838
+ createEmailTemplateRegistry,
839
+ createEmailWorker,
840
+ defineLocalTemplate,
841
+ type SmtpCapacity,
842
+ } from '@web-ts-toolkit/email-service';
843
+ import { createMongooseEmailStore } from '@web-ts-toolkit/email-service/mongoose';
844
+ import { createSmtpProvider, type SmtpProviderOptions } from '@web-ts-toolkit/email-service/smtp';
845
+
846
+ const smtpCapacity: SmtpCapacity = {
847
+ format: 'smtp-v2',
848
+ namespace: '6d36e018-b27f-4f3d-88d1-9b10ad86aaff',
849
+ maxRecipients: 51,
850
+ };
851
+
852
+ async function configureCapacityLane(connection: Connection, transport: Omit<SmtpProviderOptions, 'smtpCapacity'>) {
853
+ const store = createMongooseEmailStore(connection, { smtpCapacity });
854
+ await store.ready();
855
+ const queue = { scope: 'example-app', store, smtpCapacity };
856
+ const notice = defineLocalTemplate({
857
+ kind: 'handlebars',
858
+ revision: 'v1',
859
+ defaults: { from: { address: 'sender@example.invalid' } },
860
+ subject: { kind: 'inline', content: 'Example notice' },
861
+ text: { kind: 'inline', content: 'Synthetic message' },
862
+ parseInput: () => null,
863
+ parseData: () => ({}),
864
+ prepare: () => ({
865
+ to: Array.from({ length: 51 }, (_, i) => ({ address: `recipient-${i}@example.invalid` })),
866
+ values: {},
867
+ }),
868
+ });
869
+ const registry = createEmailTemplateRegistry({ notice }, { smtpCapacity });
870
+ const service = createEmailService({ ...queue, registry });
871
+ const relay = createEmailRelay(queue);
872
+ const batchAdmission = createEmailBatchAdmission({ service, smtpCapacity });
873
+ const smtp = createSmtpProvider({ ...transport, smtpCapacity });
874
+ const worker = createEmailWorker({ ...queue, providers: [smtp] });
875
+ const batch = createEmailBatchService({ service, worker, smtpCapacity });
876
+ const admin = createEmailAdmin(queue);
877
+ const staged = await registry.prepare(queue.scope, {
878
+ templateKey: 'notice',
879
+ input: null,
880
+ intent: 'synthetic-notice',
881
+ key: { kind: 'single', idempotencyKey: 'notice-1' },
882
+ provider: smtp.ref,
883
+ });
884
+ const admission = await relay.enqueuePrepared(staged);
885
+ return { admission, admin, batchAdmission, batch, worker };
886
+ }
887
+ ```
888
+
889
+ For development, use `createMemoryEmailStore({ smtpCapacity })` and still await `store.ready()`. Separate backings
890
+ (including independent memory stores) need different UUIDs, even in one process. For local SMTP tests, run a TLS relay
891
+ with a fixture certificate signed by a test CA. For example, supply `host: '127.0.0.1'`, the fixture `port`,
892
+ `tls: 'implicit'`, `servername: 'smtp.loopback.invalid'` (matching the certificate's DNS SAN) and `ca: [fixtureCaPem]`.
893
+ `ca` explicitly trusts the fixture CA instead of the default roots; it does not bypass hostname verification.
894
+ Both implicit TLS and required STARTTLS verify the peer; plaintext mail and plaintext authentication are not supported.
895
+
896
+ ### Envelope, queue and relay limits
897
+
898
+ - Count and size checks both apply. The canonical snapshot is capped at **2 MiB and 4,096 JSON values** in the
899
+ opted-in queue (V1 uses a 1 MiB snapshot limit). Envelope fields, metadata, attachment references, and rendered
900
+ bodies share the snapshot budget, including JSON escaping. The individual **512 KiB HTML** and **256 KiB text**
901
+ allowances do not increase. Up to five attachments may supply separate bytes (2 MiB each, 5 MiB total).
902
+ An over-limit snapshot fails with `invalid_snapshot` before insert or provider preflight. On-wire MIME is a
903
+ different size from the snapshot: allow for headers, encoding and attachments when checking the relay's limits.
904
+ - Opted-in workers default to one concurrent job (max two). `run()` defaults to four claims and four maintenance
905
+ steps (each max 16). Admin history pages default to eight activities (max 16); reconciliation and cleanup default
906
+ to four steps (max 16). A bound memory store defaults to eight jobs (max 16); a bound Mongo handle permits at
907
+ most four in-flight primitives. Do not copy larger V1 settings into a capacity queue.
908
+ - Relay recipient limits, reply latency, message size limits and throughput may require choosing a lower cap.
909
+ The adapter waits for each `RCPT TO` reply, even if the relay advertises PIPELINING. For planning, multiply the
910
+ recipient count by a conservative per-reply latency and add time for DNS, connection, TLS, other commands,
911
+ MIME transfer and the final acknowledgement. Leave reserve for jitter and worker/store operations too. At
912
+ 60 ms per reply, 1,000 RCPT replies alone use the entire 60-second provider maximum.
913
+
914
+ On verified-TLS loopback, a single 1,000-recipient transaction with 8.18 MiB of synthetic MIME took **5.851 s**
915
+ with 5 ms added per RCPT (15 s provider budget), **26.004 s** with 25 ms, and **50.980 s** with 50 ms (60 s budget).
916
+ These are single samples, not production latency estimates or a guarantee for another relay. The worker's
917
+ `limits.providerTimeoutMs` defaults to 15,000 ms and cannot exceed 60,000 ms; the effective call is further
918
+ clipped by the remaining run and lease windows, including finalization grace and clock margin. Defaults are
919
+ a 30 s run, 60 s lease and 10 s finalization grace. The two extended samples used
920
+ `limits: { providerTimeoutMs: 60_000, leaseMs: 90_000 }` and a 75,000 ms `run({ timeoutMs })` budget, not just a
921
+ higher provider timeout. Measure with representative envelopes and keep headroom; timeouts are not a flow-control
922
+ strategy.
923
+
924
+ After a partial acceptance there is no automatic resend, including to the rejected subset. Only definitive safe
925
+ transient nonacceptance authorizes a submission retry. Timeout or missing acknowledgement can leave an `unknown`
926
+ result; closing a socket does not prove that the relay discarded the message. `write_unconfirmed` is not a rollback.
927
+ Job and activity reads remain redacted. Opted-in activities include group counts and, when known, group/index
928
+ outcomes, not recipient addresses, message content, attachment references, credentials or raw SMTP replies.
929
+
930
+ ### Storage, rollout and rollback
931
+
932
+ - `format: 'smtp-v2'` selects a separate **storage** format; the public DTOs still have `version: 1`.
933
+ Every opted-in prepared command, SMTP snapshot, job summary and activity carries its `smtpCapacity` metadata,
934
+ even below 51 recipients. The field is optional in TypeScript so the types still describe V1 data, where it
935
+ must be absent. Neither queue will accept the other's staged values.
936
+ - On MongoDB the binding owns exactly `email_smtp_v2.<namespace>.jobs` and
937
+ `email_smtp_v2.<namespace>.activities`; V1 collection/model name overrides cannot be supplied with this option.
938
+ Call `ready()` before use. It checks both definitions and installs missing collections/indexes; it does not
939
+ alter existing validators, rewrite rows or touch V1 collections. A conflicting cap for an existing namespace
940
+ fails readiness. Keep the pair private and restore it together, offline, under its original binding.
941
+ - Keep the namespace and cap fixed for the lifetime of the backing queue. To change the cap, provision a fresh
942
+ namespace, verify readiness, and change routing for **new** work. Keep older and newer queues separate, each
943
+ with its own matched worker and admin. Third-party stores stay V1 unless they implement the bound storage and
944
+ limits, including checking the exact `StoreCall.smtpCapacity` before each primitive.
945
+ - To roll back, stop routing new work to the opt-in queue. Keep already staged outbox values and jobs on their
946
+ original route. Drain (or park) that lane with matching code and binding for recovery, inspection and retention;
947
+ keep V1 traffic on its existing queue. Do not point an older, V1-only runtime at the opted-in store. Do not retag,
948
+ copy or replay jobs across queues or automatically redrive uncertain work. The original lane's idempotency and
949
+ retention still apply.
950
+
951
+ ## Integration entrypoint types
425
952
 
426
953
  The integration types have their own entrypoints:
427
954
 
@@ -433,14 +960,6 @@ import type { SendGridProviderOptions } from '@web-ts-toolkit/email-service/send
433
960
  import type { MongooseEmailStoreOptions } from '@web-ts-toolkit/email-service/mongoose';
434
961
  ```
435
962
 
436
- <!-- prettier-ignore -->
437
- | Entry | Current surface | Optional peer |
438
- | --- | --- | --- |
439
- | `@web-ts-toolkit/email-service` | `EmailError`, `createEmailTemplateRegistry`, `defineLocalTemplate`, `defineSendGridTemplate`, `createEmailService`, `createEmailWorker`, `createEmailBatchService`, `createEmailAdmin`, `createMemoryEmailStore`, and shared contracts | None |
440
- | `@web-ts-toolkit/email-service/smtp` | `createSmtpProvider`, `SmtpProviderOptions` | Nodemailer `>=10.6.0 <11` (runtime only) |
441
- | `@web-ts-toolkit/email-service/sendgrid` | `createSendGridProvider`, `SendGridProviderOptions` | None (Node HTTPS) |
442
- | `@web-ts-toolkit/email-service/mongoose` | `createMongooseEmailStore`, `MongooseEmailStoreOptions` | Mongoose `>=9.12.2 <10` (declarations and caller connection) |
443
-
444
963
  The root has no runtime or declaration dependency on the optional peers. A type-only SMTP import does not require
445
964
  Nodemailer. The Mongoose runtime module can load without Mongoose, but its declarations reference the peer and
446
965
  the factory needs a caller-owned Mongoose connection. No entrypoint opens a connection, registers a model, starts