@web-ts-toolkit/email-service 0.73.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.
@@ -1,6 +1,10 @@
1
- import { U as UnixMs, j as AttemptReason, S as SmtpCapacity, a as EmailScope, n as EmailJobId, b as EmailAdmissionKey, P as ProviderRef, T as TemplateIdentity, C as Correlation, m as EmailAttemptId, B as SubmissionOutcome, e as CallOptions, A as Awaitable, l as ConfiguredEmailProvider, i as AttachmentResolver, g as EmailClock, R as RecipientResult, k as AttemptResult, p as EmailSnapshot, f as PreparedEmailCommand } from './provider-DC_av0SQ.js';
1
+ import { U as UnixMs, k as AttemptReason, S as SmtpCapacity, a as EmailScope, o as EmailJobId, b as EmailAdmissionKey, P as ProviderRef, T as TemplateIdentity, C as Correlation, n as EmailAttemptId, B as SubmissionOutcome, e as CallOptions, A as Awaitable, m as ConfiguredEmailProvider, j as AttachmentResolver, g as EmailClock, R as RecipientResult, l as AttemptResult, q as EmailSnapshot, f as PreparedEmailCommand } from './provider-CeUryYAf.js';
2
2
 
3
- /** Ordinary attempt budget and capped exponential backoff, frozen at admission. */
3
+ /**
4
+ * Frozen at admission. `maxAttempts` defaults to 3 claims, including quota deferrals with no provider call.
5
+ * Safe transient retries use jittered exponential backoff (default 1 s base, 60 s cap) and any later retry
6
+ * floor from the limiter or provider. No retry is scheduled at or after expiry.
7
+ */
4
8
  type RetryPolicy = {
5
9
  maxAttempts: number;
6
10
  baseDelayMs: number;
@@ -61,7 +65,11 @@ type CancelResult = {
61
65
  } | {
62
66
  readonly status: 'not_found';
63
67
  };
64
- /** Redrive permits one extra claim on the same snapshot and can duplicate an already accepted message. */
68
+ /**
69
+ * Resolve only the current open unknown attempt. Dismiss leaves the outcome unchanged, even after expiry.
70
+ * Redrive requires a retained unexpired snapshot and no previous redrive; it adds one claim on that same
71
+ * snapshot and can duplicate an already accepted message. Quiesce suspected old workers and review evidence first.
72
+ */
65
73
  type ResolveUnknownCommand = {
66
74
  jobId: EmailJobId;
67
75
  attemptId: EmailAttemptId;
@@ -76,7 +84,10 @@ type ResolveUnknownResult = {
76
84
  readonly job: EmailJobSummary;
77
85
  };
78
86
 
79
- /** A shared limiter must enforce the actual quota across workers/processes; a worker limiter is instance-local. */
87
+ /**
88
+ * A shared limiter must enforce the actual quota across workers/processes; a worker limiter is instance-local.
89
+ * A deferral consumes a claim without calling `submit`; `retryAfterMs` is a floor, not a wait in the run.
90
+ */
80
91
  type EmailRateLimiter = {
81
92
  scope: 'worker' | 'shared';
82
93
  tryAcquire(request: {
@@ -103,27 +114,39 @@ type EmailWorkerLimits = {
103
114
  type EmailRunOptions = CallOptions & {
104
115
  limit?: number;
105
116
  concurrency?: number;
117
+ /** Max steps for each of lease recovery and queued expiry before claims. Zero skips both sweeps. */
106
118
  maintenanceLimit?: number;
107
119
  };
108
120
  type EmailRunEntry = {
109
121
  readonly operation: 'claim' | 'recover' | 'expire';
110
122
  readonly jobId: EmailJobId;
111
123
  readonly attemptId?: EmailAttemptId;
124
+ /** `unconfirmed` does not prove rollback or non-submission. Read the current job for a durable `unknown`. */
112
125
  readonly status: JobDisposition | 'retry_scheduled' | 'unconfirmed';
126
+ /**
127
+ * `profile_unavailable` is terminal `failed`; the attempt did not submit.
128
+ * Replaying the same command does not reopen the job.
129
+ */
113
130
  readonly reason?: AttemptReason | 'attempts_exhausted';
131
+ /** A recovery reporting `false` says nothing about whether the previous owner called the provider. */
114
132
  readonly providerInvoked: boolean;
115
133
  };
116
134
  type MaintenanceStop = 'limit' | 'idle' | 'contended' | 'aborted' | 'deadline' | 'store_error';
117
135
  /** This run's confirmed progress, not an inventory of the whole queue. */
118
136
  type EmailRunReport = {
119
- readonly stop: MaintenanceStop | 'shutdown' | 'callback_capacity';
137
+ /**
138
+ * On `expiry_maintenance_required`, schedule another run for the same scope with a positive
139
+ * `maintenanceLimit` (the default does this). A backlog may need several bounded runs; retrying
140
+ * with zero maintenance alone does not clear it. The stop does not prove live work is waiting.
141
+ */
142
+ readonly stop: MaintenanceStop | 'shutdown' | 'callback_capacity' | 'expiry_maintenance_required';
120
143
  readonly items: readonly EmailRunEntry[];
121
144
  readonly counts: {
122
145
  readonly claimed: number;
123
146
  readonly recovered: number;
124
147
  readonly expiredInSweep: number;
125
148
  readonly providerCalls: number;
126
- /** Full plus partial acceptance; sandbox validations do not count. */
149
+ /** Full plus partial submission acceptance; not sandbox validation or inbox delivery. */
127
150
  readonly submitted: number;
128
151
  readonly retryScheduled: number;
129
152
  readonly accepted: number;
@@ -146,18 +169,32 @@ type EmailShutdownReport = {
146
169
  interface EmailWorker {
147
170
  readonly scope: EmailScope;
148
171
  readonly smtpCapacity?: SmtpCapacity;
149
- /** Do bounded work in this scope. The host schedules runs; only one run per instance may be active. */
172
+ /**
173
+ * Do bounded work in this scope without filtering claims by provider profile.
174
+ * The host schedules runs; only one run per instance may be active.
175
+ */
150
176
  run(options?: EmailRunOptions): Promise<EmailRunReport>;
151
177
  /** Stop permanently. `stopped` means no active run or provider I/O, not remote recall. */
152
178
  shutdown(options?: Pick<CallOptions, 'timeoutMs'>): Promise<EmailShutdownReport>;
153
179
  }
154
- /** Dependencies for a bounded worker; provider profile keys must be unique. */
180
+ /**
181
+ * Dependencies for a bounded worker. Workers sharing a queue and scope compete for jobs.
182
+ * Install new profiles and their resolvers on every competing worker before producers use them,
183
+ * and keep old ones until their work drains. The host must verify coverage across processes.
184
+ * Fleets that cannot share configuration need separately routed scopes or queues.
185
+ */
155
186
  type EmailWorkerOptions = {
156
187
  scope: EmailScope;
157
188
  /** Must match the store and every profile. Only live SMTP profiles are allowed with this option. */
158
189
  smtpCapacity?: SmtpCapacity;
159
190
  store: EmailStore;
191
+ /**
192
+ * Supply at least one configured profile; an empty array throws `invalid_config` at construction.
193
+ * Profile keys must be unique within this worker. Every competing worker needs the exact kind,
194
+ * key and mode of every active profile in its scope. Workers never substitute another profile.
195
+ */
160
196
  providers: readonly ConfiguredEmailProvider[];
197
+ /** Supply a resolver for every `resolverKey` used by work in this scope on each competing worker. */
161
198
  attachmentResolvers?: Readonly<Record<string, AttachmentResolver>>;
162
199
  rateLimiter?: EmailRateLimiter;
163
200
  clock?: EmailClock;
@@ -218,15 +255,21 @@ type CleanupReport = {
218
255
  };
219
256
  interface EmailAdmin {
220
257
  readonly scope: EmailScope;
221
- /** Read the job and its latest authoritative outcome, even before an activity is projected. */
258
+ /** Read the job and its latest authoritative outcome, even before projection. Use this to verify a current hold. */
222
259
  getJob(jobId: EmailJobId, options?: CallOptions): Promise<EmailJobSummary | null>;
223
260
  /** Cancel only before irreversible handoff and expiry; no remote recall. */
224
261
  cancel(jobId: EmailJobId, options?: CallOptions): Promise<CancelResult>;
225
- /** Dismiss or requeue an exact unknown attempt. Redrive can duplicate a previously accepted submission. */
262
+ /**
263
+ * Dismiss or requeue the exact open unknown attempt. Redrive can duplicate a previously accepted submission.
264
+ * After `write_unconfirmed`, check the current job's `resolutions` for the exact attempt and action.
265
+ */
226
266
  resolveUnknown(command: ResolveUnknownCommand, options?: CallOptions): Promise<ResolveUnknownResult>;
227
- /** Read committed activities even before source ACK. V1 default/max: 25/100; SMTP opt-in: 8/16. */
267
+ /**
268
+ * Read committed activities even before source ACK. History is not an inventory of open holds.
269
+ * V1 default/max: 25/100; SMTP opt-in: 8/16.
270
+ */
228
271
  listActivities(query?: EmailActivityQuery, options?: CallOptions): Promise<EmailActivityPage>;
229
- /** Project from the authoritative ledger; no send can result from this operation. */
272
+ /** Project from the authoritative ledger. Does not recover leases or send mail. */
230
273
  reconcile(options?: MaintenanceOptions): Promise<ReconcileReport>;
231
274
  /** Prune or retire settled, fully projected jobs after their retention windows. */
232
275
  cleanup(options?: MaintenanceOptions): Promise<CleanupReport>;
@@ -281,6 +324,10 @@ type ClaimedEmail = {
281
324
  readonly ordinal: number;
282
325
  readonly manual: boolean;
283
326
  };
327
+ /** A full claim window of due, expired jobs may hide eligible work. The signal itself makes no write. */
328
+ type StoreClaimNext<T = ClaimedEmail> = StoreNext<T> | {
329
+ readonly status: 'expiry_maintenance_required';
330
+ };
284
331
  type AttemptCommit = {
285
332
  readonly jobId: EmailJobId;
286
333
  readonly attemptId: EmailAttemptId;
@@ -303,15 +350,20 @@ type CleanupStep = 'payload_pruned' | 'retirement_started' | 'purged';
303
350
  /**
304
351
  * Scoped atomic lifecycle operations, not generic CRUD. Enforce scope in every row operation and use store
305
352
  * time for durable guards. Do not report an unconfirmed write as a definite miss or fall back to memory.
353
+ * See the installed README for the versioned adapter contracts and current follow-ups.
306
354
  */
307
355
  interface EmailStore {
308
356
  readonly smtpCapacity?: SmtpCapacity;
357
+ /** Call before use. Of the bundled stores, only V1 memory allows skipping readiness for legacy callers. */
309
358
  ready(options?: CallOptions): Promise<void>;
310
359
  findAdmission(scope: EmailScope, key: EmailAdmissionKey, call: StoreCall): Promise<{
311
360
  readonly job: EmailJobSummary;
312
361
  readonly fingerprint: string;
313
362
  } | null>;
314
- /** `duplicate` confirms a scoped admission-key collision; read the current winner and compare fingerprints. */
363
+ /**
364
+ * `duplicate` confirms a scoped admission-key collision; read the current winner and compare fingerprints.
365
+ * On a miss, new SMTP inserts require leaf attachments (no `message/*` or `multipart/*`).
366
+ */
315
367
  insert(scope: EmailScope, admission: StoreAdmission, call: StoreCall): Promise<{
316
368
  readonly status: 'inserted';
317
369
  readonly job: EmailJobSummary;
@@ -320,11 +372,16 @@ interface EmailStore {
320
372
  }>;
321
373
  findJob(scope: EmailScope, jobId: EmailJobId, call: StoreCall): Promise<EmailJobSummary | null>;
322
374
  findAttempt(scope: EmailScope, jobId: EmailJobId, attemptId: EmailAttemptId, call: StoreCall): Promise<AttemptCommit | null>;
375
+ /**
376
+ * Claim within a bounded window. `expiry_maintenance_required` means every candidate slot was filled
377
+ * by a confirmed expired queued job, not that more jobs necessarily exist. Run bounded `expireNext`
378
+ * calls in the same scope (or run a worker with a positive `maintenanceLimit`), then retry.
379
+ */
323
380
  claimNext(scope: EmailScope, claim: {
324
381
  attemptId: EmailAttemptId;
325
382
  token: LeaseToken;
326
383
  leaseMs: number;
327
- }, call: StoreCall): Promise<StoreNext<ClaimedEmail>>;
384
+ }, call: StoreCall): Promise<StoreClaimNext>;
328
385
  /** Null on a fenced operation is a definite miss, never a lost ACK. */
329
386
  renew(scope: EmailScope, fence: OwnerFence, leaseMs: number, call: StoreCall): Promise<LeaseGrant | null>;
330
387
  /** A timely positive ACK of this exact mutation is required to authorize submission. */
@@ -357,4 +414,4 @@ type MemoryEmailStoreOptions = {
357
414
  maxJobs?: number;
358
415
  };
359
416
 
360
- export type { AttemptCommit as A, StoreNext as B, CancelResult as C, EmailJobSummary as E, HandoffGrant as H, JobDisposition as J, LeaseGrant as L, MemoryEmailStoreOptions as M, OwnerFence as O, ProjectionPermit as P, RetryPolicy as R, StoreAdmission as S, UnknownResolution as U, EmailRunOptions as a, EmailRunReport as b, EmailWorker as c, EmailStore as d, RetentionPolicy as e, EmailWorkerOptions as f, EmailAdminOptions as g, EmailAdmin as h, ClaimedEmail as i, CleanupReport as j, CleanupStep as k, EmailActivity as l, EmailActivityPage as m, EmailActivityQuery as n, EmailJobState as o, EmailRateLimiter as p, EmailRunEntry as q, EmailShutdownReport as r, EmailWorkerLimits as s, LeaseToken as t, MaintenanceOptions as u, MaintenanceStop as v, ReconcileReport as w, ResolveUnknownCommand as x, ResolveUnknownResult as y, StoreCall as z };
417
+ export type { AttemptCommit as A, StoreClaimNext as B, CancelResult as C, StoreNext as D, EmailJobSummary as E, HandoffGrant as H, JobDisposition as J, LeaseGrant as L, MemoryEmailStoreOptions as M, OwnerFence as O, ProjectionPermit as P, RetryPolicy as R, StoreAdmission as S, UnknownResolution as U, EmailRunOptions as a, EmailRunReport as b, EmailWorker as c, EmailStore as d, RetentionPolicy as e, EmailWorkerOptions as f, EmailAdminOptions as g, EmailAdmin as h, ClaimedEmail as i, CleanupReport as j, CleanupStep as k, EmailActivity as l, EmailActivityPage as m, EmailActivityQuery as n, EmailJobState as o, EmailRateLimiter as p, EmailRunEntry as q, EmailShutdownReport as r, EmailWorkerLimits as s, LeaseToken as t, MaintenanceOptions as u, MaintenanceStop as v, ReconcileReport as w, ResolveUnknownCommand as x, ResolveUnknownResult as y, StoreCall as z };
@@ -1,6 +1,10 @@
1
- import { U as UnixMs, j as AttemptReason, S as SmtpCapacity, a as EmailScope, n as EmailJobId, b as EmailAdmissionKey, P as ProviderRef, T as TemplateIdentity, C as Correlation, m as EmailAttemptId, B as SubmissionOutcome, e as CallOptions, A as Awaitable, l as ConfiguredEmailProvider, i as AttachmentResolver, g as EmailClock, R as RecipientResult, k as AttemptResult, p as EmailSnapshot, f as PreparedEmailCommand } from './provider-DC_av0SQ.mjs';
1
+ import { U as UnixMs, k as AttemptReason, S as SmtpCapacity, a as EmailScope, o as EmailJobId, b as EmailAdmissionKey, P as ProviderRef, T as TemplateIdentity, C as Correlation, n as EmailAttemptId, B as SubmissionOutcome, e as CallOptions, A as Awaitable, m as ConfiguredEmailProvider, j as AttachmentResolver, g as EmailClock, R as RecipientResult, l as AttemptResult, q as EmailSnapshot, f as PreparedEmailCommand } from './provider-CeUryYAf.mjs';
2
2
 
3
- /** Ordinary attempt budget and capped exponential backoff, frozen at admission. */
3
+ /**
4
+ * Frozen at admission. `maxAttempts` defaults to 3 claims, including quota deferrals with no provider call.
5
+ * Safe transient retries use jittered exponential backoff (default 1 s base, 60 s cap) and any later retry
6
+ * floor from the limiter or provider. No retry is scheduled at or after expiry.
7
+ */
4
8
  type RetryPolicy = {
5
9
  maxAttempts: number;
6
10
  baseDelayMs: number;
@@ -61,7 +65,11 @@ type CancelResult = {
61
65
  } | {
62
66
  readonly status: 'not_found';
63
67
  };
64
- /** Redrive permits one extra claim on the same snapshot and can duplicate an already accepted message. */
68
+ /**
69
+ * Resolve only the current open unknown attempt. Dismiss leaves the outcome unchanged, even after expiry.
70
+ * Redrive requires a retained unexpired snapshot and no previous redrive; it adds one claim on that same
71
+ * snapshot and can duplicate an already accepted message. Quiesce suspected old workers and review evidence first.
72
+ */
65
73
  type ResolveUnknownCommand = {
66
74
  jobId: EmailJobId;
67
75
  attemptId: EmailAttemptId;
@@ -76,7 +84,10 @@ type ResolveUnknownResult = {
76
84
  readonly job: EmailJobSummary;
77
85
  };
78
86
 
79
- /** A shared limiter must enforce the actual quota across workers/processes; a worker limiter is instance-local. */
87
+ /**
88
+ * A shared limiter must enforce the actual quota across workers/processes; a worker limiter is instance-local.
89
+ * A deferral consumes a claim without calling `submit`; `retryAfterMs` is a floor, not a wait in the run.
90
+ */
80
91
  type EmailRateLimiter = {
81
92
  scope: 'worker' | 'shared';
82
93
  tryAcquire(request: {
@@ -103,27 +114,39 @@ type EmailWorkerLimits = {
103
114
  type EmailRunOptions = CallOptions & {
104
115
  limit?: number;
105
116
  concurrency?: number;
117
+ /** Max steps for each of lease recovery and queued expiry before claims. Zero skips both sweeps. */
106
118
  maintenanceLimit?: number;
107
119
  };
108
120
  type EmailRunEntry = {
109
121
  readonly operation: 'claim' | 'recover' | 'expire';
110
122
  readonly jobId: EmailJobId;
111
123
  readonly attemptId?: EmailAttemptId;
124
+ /** `unconfirmed` does not prove rollback or non-submission. Read the current job for a durable `unknown`. */
112
125
  readonly status: JobDisposition | 'retry_scheduled' | 'unconfirmed';
126
+ /**
127
+ * `profile_unavailable` is terminal `failed`; the attempt did not submit.
128
+ * Replaying the same command does not reopen the job.
129
+ */
113
130
  readonly reason?: AttemptReason | 'attempts_exhausted';
131
+ /** A recovery reporting `false` says nothing about whether the previous owner called the provider. */
114
132
  readonly providerInvoked: boolean;
115
133
  };
116
134
  type MaintenanceStop = 'limit' | 'idle' | 'contended' | 'aborted' | 'deadline' | 'store_error';
117
135
  /** This run's confirmed progress, not an inventory of the whole queue. */
118
136
  type EmailRunReport = {
119
- readonly stop: MaintenanceStop | 'shutdown' | 'callback_capacity';
137
+ /**
138
+ * On `expiry_maintenance_required`, schedule another run for the same scope with a positive
139
+ * `maintenanceLimit` (the default does this). A backlog may need several bounded runs; retrying
140
+ * with zero maintenance alone does not clear it. The stop does not prove live work is waiting.
141
+ */
142
+ readonly stop: MaintenanceStop | 'shutdown' | 'callback_capacity' | 'expiry_maintenance_required';
120
143
  readonly items: readonly EmailRunEntry[];
121
144
  readonly counts: {
122
145
  readonly claimed: number;
123
146
  readonly recovered: number;
124
147
  readonly expiredInSweep: number;
125
148
  readonly providerCalls: number;
126
- /** Full plus partial acceptance; sandbox validations do not count. */
149
+ /** Full plus partial submission acceptance; not sandbox validation or inbox delivery. */
127
150
  readonly submitted: number;
128
151
  readonly retryScheduled: number;
129
152
  readonly accepted: number;
@@ -146,18 +169,32 @@ type EmailShutdownReport = {
146
169
  interface EmailWorker {
147
170
  readonly scope: EmailScope;
148
171
  readonly smtpCapacity?: SmtpCapacity;
149
- /** Do bounded work in this scope. The host schedules runs; only one run per instance may be active. */
172
+ /**
173
+ * Do bounded work in this scope without filtering claims by provider profile.
174
+ * The host schedules runs; only one run per instance may be active.
175
+ */
150
176
  run(options?: EmailRunOptions): Promise<EmailRunReport>;
151
177
  /** Stop permanently. `stopped` means no active run or provider I/O, not remote recall. */
152
178
  shutdown(options?: Pick<CallOptions, 'timeoutMs'>): Promise<EmailShutdownReport>;
153
179
  }
154
- /** Dependencies for a bounded worker; provider profile keys must be unique. */
180
+ /**
181
+ * Dependencies for a bounded worker. Workers sharing a queue and scope compete for jobs.
182
+ * Install new profiles and their resolvers on every competing worker before producers use them,
183
+ * and keep old ones until their work drains. The host must verify coverage across processes.
184
+ * Fleets that cannot share configuration need separately routed scopes or queues.
185
+ */
155
186
  type EmailWorkerOptions = {
156
187
  scope: EmailScope;
157
188
  /** Must match the store and every profile. Only live SMTP profiles are allowed with this option. */
158
189
  smtpCapacity?: SmtpCapacity;
159
190
  store: EmailStore;
191
+ /**
192
+ * Supply at least one configured profile; an empty array throws `invalid_config` at construction.
193
+ * Profile keys must be unique within this worker. Every competing worker needs the exact kind,
194
+ * key and mode of every active profile in its scope. Workers never substitute another profile.
195
+ */
160
196
  providers: readonly ConfiguredEmailProvider[];
197
+ /** Supply a resolver for every `resolverKey` used by work in this scope on each competing worker. */
161
198
  attachmentResolvers?: Readonly<Record<string, AttachmentResolver>>;
162
199
  rateLimiter?: EmailRateLimiter;
163
200
  clock?: EmailClock;
@@ -218,15 +255,21 @@ type CleanupReport = {
218
255
  };
219
256
  interface EmailAdmin {
220
257
  readonly scope: EmailScope;
221
- /** Read the job and its latest authoritative outcome, even before an activity is projected. */
258
+ /** Read the job and its latest authoritative outcome, even before projection. Use this to verify a current hold. */
222
259
  getJob(jobId: EmailJobId, options?: CallOptions): Promise<EmailJobSummary | null>;
223
260
  /** Cancel only before irreversible handoff and expiry; no remote recall. */
224
261
  cancel(jobId: EmailJobId, options?: CallOptions): Promise<CancelResult>;
225
- /** Dismiss or requeue an exact unknown attempt. Redrive can duplicate a previously accepted submission. */
262
+ /**
263
+ * Dismiss or requeue the exact open unknown attempt. Redrive can duplicate a previously accepted submission.
264
+ * After `write_unconfirmed`, check the current job's `resolutions` for the exact attempt and action.
265
+ */
226
266
  resolveUnknown(command: ResolveUnknownCommand, options?: CallOptions): Promise<ResolveUnknownResult>;
227
- /** Read committed activities even before source ACK. V1 default/max: 25/100; SMTP opt-in: 8/16. */
267
+ /**
268
+ * Read committed activities even before source ACK. History is not an inventory of open holds.
269
+ * V1 default/max: 25/100; SMTP opt-in: 8/16.
270
+ */
228
271
  listActivities(query?: EmailActivityQuery, options?: CallOptions): Promise<EmailActivityPage>;
229
- /** Project from the authoritative ledger; no send can result from this operation. */
272
+ /** Project from the authoritative ledger. Does not recover leases or send mail. */
230
273
  reconcile(options?: MaintenanceOptions): Promise<ReconcileReport>;
231
274
  /** Prune or retire settled, fully projected jobs after their retention windows. */
232
275
  cleanup(options?: MaintenanceOptions): Promise<CleanupReport>;
@@ -281,6 +324,10 @@ type ClaimedEmail = {
281
324
  readonly ordinal: number;
282
325
  readonly manual: boolean;
283
326
  };
327
+ /** A full claim window of due, expired jobs may hide eligible work. The signal itself makes no write. */
328
+ type StoreClaimNext<T = ClaimedEmail> = StoreNext<T> | {
329
+ readonly status: 'expiry_maintenance_required';
330
+ };
284
331
  type AttemptCommit = {
285
332
  readonly jobId: EmailJobId;
286
333
  readonly attemptId: EmailAttemptId;
@@ -303,15 +350,20 @@ type CleanupStep = 'payload_pruned' | 'retirement_started' | 'purged';
303
350
  /**
304
351
  * Scoped atomic lifecycle operations, not generic CRUD. Enforce scope in every row operation and use store
305
352
  * time for durable guards. Do not report an unconfirmed write as a definite miss or fall back to memory.
353
+ * See the installed README for the versioned adapter contracts and current follow-ups.
306
354
  */
307
355
  interface EmailStore {
308
356
  readonly smtpCapacity?: SmtpCapacity;
357
+ /** Call before use. Of the bundled stores, only V1 memory allows skipping readiness for legacy callers. */
309
358
  ready(options?: CallOptions): Promise<void>;
310
359
  findAdmission(scope: EmailScope, key: EmailAdmissionKey, call: StoreCall): Promise<{
311
360
  readonly job: EmailJobSummary;
312
361
  readonly fingerprint: string;
313
362
  } | null>;
314
- /** `duplicate` confirms a scoped admission-key collision; read the current winner and compare fingerprints. */
363
+ /**
364
+ * `duplicate` confirms a scoped admission-key collision; read the current winner and compare fingerprints.
365
+ * On a miss, new SMTP inserts require leaf attachments (no `message/*` or `multipart/*`).
366
+ */
315
367
  insert(scope: EmailScope, admission: StoreAdmission, call: StoreCall): Promise<{
316
368
  readonly status: 'inserted';
317
369
  readonly job: EmailJobSummary;
@@ -320,11 +372,16 @@ interface EmailStore {
320
372
  }>;
321
373
  findJob(scope: EmailScope, jobId: EmailJobId, call: StoreCall): Promise<EmailJobSummary | null>;
322
374
  findAttempt(scope: EmailScope, jobId: EmailJobId, attemptId: EmailAttemptId, call: StoreCall): Promise<AttemptCommit | null>;
375
+ /**
376
+ * Claim within a bounded window. `expiry_maintenance_required` means every candidate slot was filled
377
+ * by a confirmed expired queued job, not that more jobs necessarily exist. Run bounded `expireNext`
378
+ * calls in the same scope (or run a worker with a positive `maintenanceLimit`), then retry.
379
+ */
323
380
  claimNext(scope: EmailScope, claim: {
324
381
  attemptId: EmailAttemptId;
325
382
  token: LeaseToken;
326
383
  leaseMs: number;
327
- }, call: StoreCall): Promise<StoreNext<ClaimedEmail>>;
384
+ }, call: StoreCall): Promise<StoreClaimNext>;
328
385
  /** Null on a fenced operation is a definite miss, never a lost ACK. */
329
386
  renew(scope: EmailScope, fence: OwnerFence, leaseMs: number, call: StoreCall): Promise<LeaseGrant | null>;
330
387
  /** A timely positive ACK of this exact mutation is required to authorize submission. */
@@ -357,4 +414,4 @@ type MemoryEmailStoreOptions = {
357
414
  maxJobs?: number;
358
415
  };
359
416
 
360
- export type { AttemptCommit as A, StoreNext as B, CancelResult as C, EmailJobSummary as E, HandoffGrant as H, JobDisposition as J, LeaseGrant as L, MemoryEmailStoreOptions as M, OwnerFence as O, ProjectionPermit as P, RetryPolicy as R, StoreAdmission as S, UnknownResolution as U, EmailRunOptions as a, EmailRunReport as b, EmailWorker as c, EmailStore as d, RetentionPolicy as e, EmailWorkerOptions as f, EmailAdminOptions as g, EmailAdmin as h, ClaimedEmail as i, CleanupReport as j, CleanupStep as k, EmailActivity as l, EmailActivityPage as m, EmailActivityQuery as n, EmailJobState as o, EmailRateLimiter as p, EmailRunEntry as q, EmailShutdownReport as r, EmailWorkerLimits as s, LeaseToken as t, MaintenanceOptions as u, MaintenanceStop as v, ReconcileReport as w, ResolveUnknownCommand as x, ResolveUnknownResult as y, StoreCall as z };
417
+ export type { AttemptCommit as A, StoreClaimNext as B, CancelResult as C, StoreNext as D, EmailJobSummary as E, HandoffGrant as H, JobDisposition as J, LeaseGrant as L, MemoryEmailStoreOptions as M, OwnerFence as O, ProjectionPermit as P, RetryPolicy as R, StoreAdmission as S, UnknownResolution as U, EmailRunOptions as a, EmailRunReport as b, EmailWorker as c, EmailStore as d, RetentionPolicy as e, EmailWorkerOptions as f, EmailAdminOptions as g, EmailAdmin as h, ClaimedEmail as i, CleanupReport as j, CleanupStep as k, EmailActivity as l, EmailActivityPage as m, EmailActivityQuery as n, EmailJobState as o, EmailRateLimiter as p, EmailRunEntry as q, EmailShutdownReport as r, EmailWorkerLimits as s, LeaseToken as t, MaintenanceOptions as u, MaintenanceStop as v, ReconcileReport as w, ResolveUnknownCommand as x, ResolveUnknownResult as y, StoreCall as z };