durability 3.0.1 → 4.0.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.
@@ -28,6 +28,33 @@ export declare const durabilityFanoutMigrations: {
28
28
  up: string;
29
29
  down: string;
30
30
  }[];
31
+ /**
32
+ * Ordered SQLite migrations for the outbound event log owned by
33
+ * {@link DurabilitySocket}. Applied automatically on construction.
34
+ */
35
+ export declare const durabilitySocketMigrations: {
36
+ name: string;
37
+ up: string;
38
+ down: string;
39
+ }[];
40
+ /**
41
+ * Ordered SQLite migrations for the retained log and its consumer cursors.
42
+ * Applied automatically on construction.
43
+ */
44
+ export declare const durabilityLogMigrations: {
45
+ name: string;
46
+ up: string;
47
+ down: string;
48
+ }[];
49
+ /**
50
+ * Leases let several workers consume one log in parallel without handing the
51
+ * same offsets to two of them. Applied automatically when leases are enabled.
52
+ */
53
+ export declare const durabilityLogLeaseMigrations: {
54
+ name: string;
55
+ up: string;
56
+ down: string;
57
+ }[];
31
58
  /** Migration names changed by one migrate call. */
32
59
  export type DurabilityMigrationResult = {
33
60
  /** Migrations applied in ascending order. */
@@ -35,7 +62,7 @@ export type DurabilityMigrationResult = {
35
62
  /** Migrations reverted in descending order. */
36
63
  rolledBack: string[];
37
64
  };
38
- export type MigrationCapability = 'operations' | 'namedAlarms' | 'fanout';
65
+ export type MigrationCapability = 'operations' | 'namedAlarms' | 'fanout' | 'socket' | 'log' | 'logLeases';
39
66
  type MigrationStorage = Pick<DurableObjectStorage, 'sql' | 'transactionSync'>;
40
67
  /**
41
68
  * Moves one capability's schema to a target migration, applying or reverting as
@@ -222,6 +222,106 @@ export const durabilityFanoutMigrations = [
222
222
  `,
223
223
  },
224
224
  ];
225
+ /**
226
+ * Ordered SQLite migrations for the outbound event log owned by
227
+ * {@link DurabilitySocket}. Applied automatically on construction.
228
+ */
229
+ export const durabilitySocketMigrations = [
230
+ {
231
+ name: 'durability_0006_create_socket_events',
232
+ up: `
233
+ CREATE TABLE IF NOT EXISTS durability_socket_events (
234
+ seq INTEGER PRIMARY KEY AUTOINCREMENT,
235
+ name TEXT NOT NULL,
236
+ payload TEXT NOT NULL,
237
+ created_at INTEGER NOT NULL
238
+ );
239
+ `,
240
+ down: 'DROP TABLE IF EXISTS durability_socket_events;',
241
+ },
242
+ ];
243
+ /**
244
+ * Ordered SQLite migrations for the retained log and its consumer cursors.
245
+ * Applied automatically on construction.
246
+ */
247
+ export const durabilityLogMigrations = [
248
+ {
249
+ name: 'durability_0007_create_log',
250
+ up: `
251
+ CREATE TABLE IF NOT EXISTS durability_log_records (
252
+ "offset" INTEGER PRIMARY KEY,
253
+ dedup_key TEXT NOT NULL UNIQUE,
254
+ payload TEXT NOT NULL,
255
+ bytes INTEGER NOT NULL,
256
+ appended_at INTEGER NOT NULL
257
+ );
258
+ CREATE INDEX IF NOT EXISTS durability_log_records_appended_idx
259
+ ON durability_log_records (appended_at, "offset");
260
+ CREATE TABLE IF NOT EXISTS durability_log_cursors (
261
+ consumer TEXT PRIMARY KEY,
262
+ "offset" INTEGER NOT NULL,
263
+ committed_at INTEGER NOT NULL
264
+ );
265
+ CREATE TABLE IF NOT EXISTS durability_log_segments (
266
+ first_offset INTEGER PRIMARY KEY,
267
+ last_offset INTEGER NOT NULL,
268
+ locator TEXT NOT NULL,
269
+ bytes INTEGER NOT NULL,
270
+ flushed_at INTEGER NOT NULL
271
+ );
272
+ CREATE TABLE IF NOT EXISTS durability_log_seq (
273
+ id INTEGER PRIMARY KEY CHECK (id = 1),
274
+ next_offset INTEGER NOT NULL,
275
+ total_bytes INTEGER NOT NULL
276
+ );
277
+ INSERT OR IGNORE INTO durability_log_seq (id, next_offset, total_bytes)
278
+ VALUES (1, 0, 0);
279
+ `,
280
+ down: `
281
+ DROP INDEX IF EXISTS durability_log_records_appended_idx;
282
+ DROP TABLE IF EXISTS durability_log_records;
283
+ DROP TABLE IF EXISTS durability_log_cursors;
284
+ DROP TABLE IF EXISTS durability_log_segments;
285
+ DROP TABLE IF EXISTS durability_log_seq;
286
+ `,
287
+ },
288
+ ];
289
+ /**
290
+ * Leases let several workers consume one log in parallel without handing the
291
+ * same offsets to two of them. Applied automatically when leases are enabled.
292
+ */
293
+ export const durabilityLogLeaseMigrations = [
294
+ {
295
+ name: 'durability_0008_create_log_leases',
296
+ up: `
297
+ CREATE TABLE IF NOT EXISTS durability_log_leases (
298
+ batch_id TEXT PRIMARY KEY,
299
+ consumer TEXT NOT NULL,
300
+ first_offset INTEGER NOT NULL,
301
+ last_offset INTEGER NOT NULL,
302
+ state TEXT NOT NULL
303
+ CHECK (state IN ('active', 'pending', 'acked', 'skipped')),
304
+ attempt INTEGER NOT NULL,
305
+ expires_at INTEGER NOT NULL,
306
+ created_at INTEGER NOT NULL
307
+ );
308
+ CREATE INDEX IF NOT EXISTS durability_log_leases_claim_idx
309
+ ON durability_log_leases (consumer, state, expires_at, first_offset);
310
+ CREATE INDEX IF NOT EXISTS durability_log_leases_order_idx
311
+ ON durability_log_leases (consumer, first_offset);
312
+ CREATE TABLE IF NOT EXISTS durability_log_allocations (
313
+ consumer TEXT PRIMARY KEY,
314
+ allocated_offset INTEGER NOT NULL
315
+ );
316
+ `,
317
+ down: `
318
+ DROP INDEX IF EXISTS durability_log_leases_claim_idx;
319
+ DROP INDEX IF EXISTS durability_log_leases_order_idx;
320
+ DROP TABLE IF EXISTS durability_log_leases;
321
+ DROP TABLE IF EXISTS durability_log_allocations;
322
+ `,
323
+ },
324
+ ];
225
325
  /**
226
326
  * Newer library versions may leave migrations this one does not know about.
227
327
  * On downgrade their stored `down` scripts are run, but only this many, so an
@@ -1,15 +1,12 @@
1
1
  import { type Emit, type LifecycleEntity, type LifecycleHook } from './lifecycle.js';
2
2
  import { type MigrationCapability } from './migrations.js';
3
3
  import { type AttemptPolicy } from './policy.js';
4
- import { type DurabilityStorage, type DurabilityStorageTransaction, type DurableRecord, type RecordKind } from './storage.js';
4
+ import { type DurableTable } from './storage.js';
5
5
  import type { DurableMigrations } from '@durability/storage';
6
6
  /** The Durable Object state durability needs: storage plus optional `waitUntil`. */
7
7
  export type DurabilityContext = Pick<DurableObjectState, 'storage'> & Partial<Pick<DurableObjectState, 'waitUntil'>>;
8
- export type DurabilityStorageBackend = 'sqlite' | 'kv';
9
8
  /** Options for the scheduler shared by every durability helper in one Durable Object. */
10
9
  export type DurabilitySchedulerOptions = {
11
- /** Storage backend configured for the Durable Object class. Defaults to SQLite. */
12
- storageBackend?: DurabilityStorageBackend;
13
10
  /** Maximum handlers running at once across eager operations and alarm work. Defaults to 10. */
14
11
  alarmConcurrency?: number;
15
12
  /** Physical-alarm delay from 1 to 15 seconds. Defaults to 15 seconds. */
@@ -31,11 +28,17 @@ export type SchedulerAttachment = {
31
28
  } | (DurabilitySchedulerConfig & {
32
29
  scheduler?: never;
33
30
  });
34
- /** One record kind attached to the scheduler: how to find and run its due work. */
31
+ /** One record table attached to the scheduler: how to find and run its due work. */
35
32
  export type Participant = {
36
- kind: RecordKind;
33
+ table: DurableTable;
37
34
  runDue(now: number, info: AlarmInvocationInfo | undefined): Promise<void>;
38
35
  };
36
+ /**
37
+ * Called after a record may have settled. Successful completions pass the
38
+ * executed row because some tables delete it on success; other changes pass
39
+ * nothing and listeners re-read storage.
40
+ */
41
+ export type SettlementListener = (completed?: ExecutionSpec['row']) => void;
39
42
  export type ActiveExecution = {
40
43
  generation: string;
41
44
  createdAt: number;
@@ -44,9 +47,12 @@ export type ActiveExecution = {
44
47
  };
45
48
  /** Everything that differs between running a durable operation and a named alarm attempt. */
46
49
  export type ExecutionSpec = {
47
- kind: RecordKind;
50
+ table: DurableTable;
48
51
  key: string;
49
- row: DurableRecord;
52
+ row: {
53
+ generation_id: string;
54
+ created_at: number;
55
+ };
50
56
  label: string;
51
57
  entity: LifecycleEntity;
52
58
  active: Map<string, ActiveExecution>;
@@ -60,17 +66,16 @@ export type ExecutionSpec = {
60
66
  * undefined when a newer generation won. May throw to turn the success into
61
67
  * a failure.
62
68
  */
63
- complete: (result: unknown, attempt: number) => Promise<number | undefined>;
69
+ complete: (result: unknown, attempt: number) => number | undefined;
64
70
  /** Kind-specific terminal rule beyond non-retryable errors and exhausted attempts. */
65
71
  isTerminal: (error: unknown) => boolean;
66
72
  };
67
73
  /**
68
- * Shared machinery behind {@link DurabilityScheduler}: storage, the physical
74
+ * Shared machinery behind {@link DurabilityScheduler}: transactions, the physical
69
75
  * alarm, the concurrency pool, and the attempt lifecycle. Package-internal.
70
76
  */
71
77
  export declare class Engine {
72
- readonly storage: DurabilityStorage;
73
- private readonly backend;
78
+ readonly sql: SqlStorage;
74
79
  private readonly context;
75
80
  private readonly alarmConcurrency;
76
81
  private readonly alarmMinDelayMs;
@@ -80,24 +85,34 @@ export declare class Engine {
80
85
  private readonly permitWaiters;
81
86
  private alarmRefresh;
82
87
  private earlyAlarm;
83
- private readonly transactionReconciliations;
88
+ private readonly watchers;
84
89
  constructor(context: DurabilityContext, options: DurabilitySchedulerOptions);
85
90
  register(participant: Participant): void;
86
91
  waitUntil(promise: Promise<unknown>, onError: (error: unknown) => void): void;
87
92
  emitter(hook: LifecycleHook | undefined): Emit;
88
- /** Applies a helper's SQLite migrations; KV storage has no schema. */
93
+ /** Applies a helper's SQLite migrations. */
89
94
  migrateSchema(capability: MigrationCapability, migrations: DurableMigrations): void;
90
- /** Runs a storage transaction and publishes its timer state only after commit. */
91
- transaction<T>(callback: (transaction: DurabilityStorageTransaction) => Promise<T>): Promise<T>;
92
- reconcile(transaction: DurabilityStorageTransaction): Promise<void>;
95
+ /** Runs synchronous writes atomically without touching the physical alarm. */
96
+ transactionSync<T>(write: (sql: SqlStorage) => T): T;
97
+ /**
98
+ * Runs the writes and reconciles the physical alarm in one storage
99
+ * transaction, then publishes the in-memory timer only after commit.
100
+ */
101
+ transaction<T>(write: (sql: SqlStorage) => T): Promise<T>;
102
+ /** Returns the earliest pending time and maintains its bounded physical fallback. */
103
+ private reconcile;
93
104
  private scheduleEarlyAlarm;
94
105
  /** Coalesces concurrent refresh requests into one reconciliation transaction. */
95
106
  scheduleNextAlarm(): Promise<void>;
96
107
  /**
97
108
  * Aborts matching active handlers, then deletes one kind's records created
98
- * before the timestamp, reconciling the alarm after each committed batch.
109
+ * before the timestamp and reconciles the alarm in the same transaction.
99
110
  */
100
- purge(kind: RecordKind, before: number, active: Map<string, ActiveExecution>, abortReason: string): Promise<number>;
111
+ purge(table: DurableTable, before: number, active: Map<string, ActiveExecution>, abortReason: string): Promise<number>;
112
+ /** In-memory only: listeners never survive eviction. */
113
+ watch(table: DurableTable, key: string, listener: SettlementListener): () => void;
114
+ /** Call only after the change has committed. */
115
+ notify(table: DurableTable, key: string, completed?: ExecutionSpec['row']): void;
101
116
  tryAcquirePermit(): (() => void) | undefined;
102
117
  acquirePermit(): Promise<() => void>;
103
118
  private createRelease;
@@ -118,7 +133,7 @@ export declare class Engine {
118
133
  private settleFailure;
119
134
  }
120
135
  /**
121
- * Owns the Durable Object's physical alarm, storage backend, and concurrency
136
+ * Owns the Durable Object's physical alarm, storage, and concurrency
122
137
  * pool so {@link Durability} and {@link DurabilityAlarms} can share them.
123
138
  *
124
139
  * Construct one per Durable Object when using both helpers, pass it to each,
package/dist/scheduler.js CHANGED
@@ -1,14 +1,15 @@
1
1
  import { z } from 'zod';
2
2
  import { DurableRetryPolicyError, isErrorInstance, isNonRetryable, reportFailure, serializeError, } from './errors.js';
3
- import { createKvDurabilityStorage } from './kv-storage.js';
4
3
  import { createEmitter, } from './lifecycle.js';
5
4
  import { migrate } from './migrations.js';
6
5
  import { assertPositiveInteger } from './policy.js';
7
- import { createSqliteDurabilityStorage } from './sqlite-storage.js';
8
- import { reconcilePhysicalAlarm, } from './storage.js';
9
- const storageBackendSchema = z.enum(['sqlite', 'kv']);
6
+ import { claimAttempt, exhaustAttempts, updateAttempt, } from './storage.js';
10
7
  const minAlarmDelayMs = 1000;
11
8
  const maxAlarmDelayMs = 15000;
9
+ const nextAttemptRowSchema = z.object({
10
+ next_attempt_at: z.number().int().nonnegative(),
11
+ });
12
+ const countRowSchema = z.object({ count: z.number().int().nonnegative() });
12
13
  const decideRetry = (spec, attempt, error) => {
13
14
  const terminal = isNonRetryable(error) ||
14
15
  attempt >= spec.policy.maxAttempts ||
@@ -48,20 +49,16 @@ const decideRetry = (spec, attempt, error) => {
48
49
  }
49
50
  };
50
51
  /**
51
- * Shared machinery behind {@link DurabilityScheduler}: storage, the physical
52
+ * Shared machinery behind {@link DurabilityScheduler}: transactions, the physical
52
53
  * alarm, the concurrency pool, and the attempt lifecycle. Package-internal.
53
54
  */
54
55
  export class Engine {
55
56
  constructor(context, options) {
56
57
  this.participants = [];
57
58
  this.permitWaiters = [];
58
- this.transactionReconciliations = new WeakMap();
59
+ this.watchers = new Map();
59
60
  this.context = context;
60
- this.backend = storageBackendSchema.parse(options.storageBackend ?? 'sqlite');
61
- this.storage =
62
- this.backend === 'kv'
63
- ? createKvDurabilityStorage(context.storage)
64
- : createSqliteDurabilityStorage(context.storage);
61
+ this.sql = context.storage.sql;
65
62
  this.alarmConcurrency = options.alarmConcurrency ?? 10;
66
63
  this.alarmMinDelayMs = options.alarmMinDelayMs ?? 15000;
67
64
  this.alarmHandoffMs = options.alarmHandoffMs ?? 14 * 60000;
@@ -75,8 +72,9 @@ export class Engine {
75
72
  this.availablePermits = this.alarmConcurrency;
76
73
  }
77
74
  register(participant) {
78
- if (this.participants.some(({ kind }) => kind === participant.kind)) {
79
- throw new Error(`A ${participant.kind} helper is already attached to this scheduler`);
75
+ const { name } = participant.table;
76
+ if (this.participants.some(({ table }) => table.name === name)) {
77
+ throw new Error(`A ${name} helper is already attached to this scheduler`);
80
78
  }
81
79
  this.participants.push(participant);
82
80
  }
@@ -94,37 +92,55 @@ export class Engine {
94
92
  emitter(hook) {
95
93
  return createEmitter(hook, (promise) => this.context.waitUntil?.(promise));
96
94
  }
97
- /** Applies a helper's SQLite migrations; KV storage has no schema. */
95
+ /** Applies a helper's SQLite migrations. */
98
96
  migrateSchema(capability, migrations) {
99
- if (this.backend === 'sqlite') {
100
- migrate(this.context.storage, capability, migrations, undefined);
101
- }
97
+ migrate(this.context.storage, capability, migrations, undefined);
102
98
  }
103
- /** Runs a storage transaction and publishes its timer state only after commit. */
104
- async transaction(callback) {
105
- let reconciliation;
106
- const result = await this.storage.transaction(async (transaction) => {
107
- reconciliation = { nextPendingAt: undefined, reconciled: false };
108
- this.transactionReconciliations.set(transaction, reconciliation);
109
- try {
110
- return await callback(transaction);
111
- }
112
- finally {
113
- this.transactionReconciliations.delete(transaction);
114
- }
99
+ /** Runs synchronous writes atomically without touching the physical alarm. */
100
+ transactionSync(write) {
101
+ return this.context.storage.transactionSync(() => write(this.sql));
102
+ }
103
+ /**
104
+ * Runs the writes and reconciles the physical alarm in one storage
105
+ * transaction, then publishes the in-memory timer only after commit.
106
+ */
107
+ async transaction(write) {
108
+ let nextPendingAt;
109
+ const result = await this.context.storage.transaction(async (transaction) => {
110
+ const value = write(this.sql);
111
+ nextPendingAt = await this.reconcile(transaction);
112
+ return value;
115
113
  });
116
- if (reconciliation?.reconciled) {
117
- this.scheduleEarlyAlarm(reconciliation.nextPendingAt);
118
- }
114
+ this.scheduleEarlyAlarm(nextPendingAt);
119
115
  return result;
120
116
  }
121
- async reconcile(transaction) {
122
- const reconciliation = this.transactionReconciliations.get(transaction);
123
- if (!reconciliation) {
124
- throw new Error('Scheduler reconciliation requires an Engine transaction');
117
+ /** Returns the earliest pending time and maintains its bounded physical fallback. */
118
+ async reconcile(physicalAlarm) {
119
+ const scheduled = this.participants.flatMap(({ table }) => nextAttemptRowSchema
120
+ .array()
121
+ .parse(this.sql
122
+ .exec(`SELECT next_attempt_at FROM ${table.name}
123
+ WHERE status = 'pending'
124
+ ORDER BY next_attempt_at ASC
125
+ LIMIT 1`)
126
+ .toArray())
127
+ .map((row) => row.next_attempt_at));
128
+ const nextAlarmAt = scheduled.length === 0 ? undefined : Math.min(...scheduled);
129
+ const currentAlarm = await physicalAlarm.getAlarm();
130
+ if (nextAlarmAt === undefined) {
131
+ if (currentAlarm !== null) {
132
+ await physicalAlarm.deleteAlarm();
133
+ }
134
+ return undefined;
125
135
  }
126
- reconciliation.nextPendingAt = await reconcilePhysicalAlarm(transaction, this.participants.map(({ kind }) => kind), this.alarmMinDelayMs);
127
- reconciliation.reconciled = true;
136
+ const target = Math.max(nextAlarmAt, Date.now() + this.alarmMinDelayMs);
137
+ // Preserve a fallback inside this range so frequent reconciliation cannot push it later.
138
+ if (currentAlarm === null ||
139
+ currentAlarm < nextAlarmAt ||
140
+ currentAlarm > target) {
141
+ await physicalAlarm.setAlarm(target);
142
+ }
143
+ return nextAlarmAt;
128
144
  }
129
145
  scheduleEarlyAlarm(timestamp) {
130
146
  if (this.earlyAlarm?.timestamp === timestamp) {
@@ -154,16 +170,16 @@ export class Engine {
154
170
  if (this.alarmRefresh) {
155
171
  return this.alarmRefresh;
156
172
  }
157
- this.alarmRefresh = this.transaction((transaction) => this.reconcile(transaction)).finally(() => {
173
+ this.alarmRefresh = this.transaction(() => undefined).finally(() => {
158
174
  this.alarmRefresh = undefined;
159
175
  });
160
176
  return this.alarmRefresh;
161
177
  }
162
178
  /**
163
179
  * Aborts matching active handlers, then deletes one kind's records created
164
- * before the timestamp, reconciling the alarm after each committed batch.
180
+ * before the timestamp and reconciles the alarm in the same transaction.
165
181
  */
166
- async purge(kind, before, active, abortReason) {
182
+ async purge(table, before, active, abortReason) {
167
183
  if (!Number.isSafeInteger(before) || before < 0) {
168
184
  throw new RangeError('timestamp must be a non-negative safe integer');
169
185
  }
@@ -172,18 +188,40 @@ export class Engine {
172
188
  running.controller?.abort(new Error(abortReason));
173
189
  }
174
190
  }
175
- let total = 0;
176
- let removed = 0;
177
- do {
178
- // eslint-disable-next-line no-await-in-loop
179
- removed = await this.transaction(async (transaction) => {
180
- const count = await transaction[kind].deleteCreatedBefore(before);
181
- await this.reconcile(transaction);
182
- return count;
183
- });
184
- total += removed;
185
- } while (removed > 0);
186
- return total;
191
+ const removed = await this.transaction((sql) => {
192
+ const { count } = countRowSchema.parse(sql
193
+ .exec(`SELECT COUNT(*) AS count FROM ${table.name} WHERE created_at < ?`, before)
194
+ .toArray()[0]);
195
+ sql.exec(`DELETE FROM ${table.name} WHERE created_at < ?`, before);
196
+ return count;
197
+ });
198
+ if (removed > 0) {
199
+ for (const key of this.watchers.get(table.name)?.keys() ?? []) {
200
+ this.notify(table, key);
201
+ }
202
+ }
203
+ return removed;
204
+ }
205
+ /** In-memory only: listeners never survive eviction. */
206
+ watch(table, key, listener) {
207
+ const byKey = this.watchers.get(table.name) ??
208
+ new Map();
209
+ this.watchers.set(table.name, byKey);
210
+ const listeners = byKey.get(key) ?? new Set();
211
+ byKey.set(key, listeners);
212
+ listeners.add(listener);
213
+ return () => {
214
+ listeners.delete(listener);
215
+ if (listeners.size === 0 && byKey.get(key) === listeners) {
216
+ byKey.delete(key);
217
+ }
218
+ };
219
+ }
220
+ /** Call only after the change has committed. */
221
+ notify(table, key, completed) {
222
+ for (const listener of this.watchers.get(table.name)?.get(key) ?? []) {
223
+ listener(completed);
224
+ }
187
225
  }
188
226
  tryAcquirePermit() {
189
227
  if (this.availablePermits === 0) {
@@ -261,7 +299,7 @@ export class Engine {
261
299
  await this.scheduleNextAlarm();
262
300
  }
263
301
  armForHandoff(timestamp) {
264
- return this.storage.transaction(async ({ physicalAlarm }) => {
302
+ return this.context.storage.transaction(async (physicalAlarm) => {
265
303
  const currentAlarm = await physicalAlarm.getAlarm();
266
304
  const target = Math.max(timestamp, Date.now() + this.alarmMinDelayMs);
267
305
  if (currentAlarm === null || currentAlarm > target) {
@@ -298,7 +336,7 @@ export class Engine {
298
336
  };
299
337
  const execution = (async () => {
300
338
  releasePermit ?? (releasePermit = await this.acquirePermit());
301
- const attempt = await this.storage[spec.kind].claimAttempt(key, row.generation_id, policy.maxAttempts);
339
+ const attempt = claimAttempt(this.sql, spec.table, key, row.generation_id, policy.maxAttempts);
302
340
  if (attempt === undefined) {
303
341
  await this.failExhausted(spec);
304
342
  return;
@@ -330,8 +368,9 @@ export class Engine {
330
368
  }, policy.attemptTimeoutMs);
331
369
  });
332
370
  const result = await Promise.race([handlerResult, timeoutResult]);
333
- const timestamp = await spec.complete(result, attempt);
371
+ const timestamp = spec.complete(result, attempt);
334
372
  if (timestamp !== undefined) {
373
+ this.notify(spec.table, key, row);
335
374
  spec.emit({
336
375
  ...spec.entity,
337
376
  type: 'attempt_settled',
@@ -339,6 +378,7 @@ export class Engine {
339
378
  attempt,
340
379
  durationMs: Math.max(0, timestamp - startedAt),
341
380
  outcome: 'completed',
381
+ result,
342
382
  });
343
383
  }
344
384
  }
@@ -363,50 +403,32 @@ export class Engine {
363
403
  }
364
404
  async failExhausted(spec) {
365
405
  const { key, row, policy } = spec;
366
- const current = await this.storage[spec.kind].get(key);
367
- if (current?.generation_id !== row.generation_id ||
368
- current.status !== 'pending' ||
369
- current.attempt < policy.maxAttempts) {
406
+ const exhausted = serializeError(spec.exhaustedError());
407
+ const attempt = await this.transaction((sql) => exhaustAttempts(sql, spec.table, key, row.generation_id, policy.maxAttempts, exhausted));
408
+ if (attempt === undefined) {
370
409
  return;
371
410
  }
372
- const exhausted = serializeError(spec.exhaustedError());
373
- let updated = false;
374
- await this.transaction(async (transaction) => {
375
- updated = await transaction[spec.kind].exhaust(key, row.generation_id, policy.maxAttempts, {
376
- status: 'failed',
377
- last_error: exhausted.message,
378
- last_error_name: exhausted.name,
379
- });
380
- await this.reconcile(transaction);
411
+ this.notify(spec.table, key);
412
+ spec.emit({
413
+ ...spec.entity,
414
+ type: 'terminal',
415
+ timestamp: Date.now(),
416
+ attempt,
417
+ reason: 'attempts_exhausted',
418
+ error: exhausted,
381
419
  });
382
- if (updated) {
383
- spec.emit({
384
- ...spec.entity,
385
- type: 'terminal',
386
- timestamp: Date.now(),
387
- attempt: current.attempt,
388
- reason: 'attempts_exhausted',
389
- error: exhausted,
390
- });
391
- }
392
420
  }
393
421
  async settleFailure(spec, attempt, startedAt, caught) {
394
422
  const { key, row } = spec;
395
423
  const decision = decideRetry(spec, attempt, caught);
396
424
  const serializedError = serializeError(decision.error);
397
- let updated = false;
398
- await this.transaction(async (transaction) => {
399
- updated = await transaction[spec.kind].settle(key, row.generation_id, attempt, {
400
- status: decision.terminal ? 'failed' : 'pending',
401
- next_attempt_at: decision.nextAttemptAt,
402
- last_error: serializedError.message,
403
- last_error_name: serializedError.name,
404
- });
405
- await this.reconcile(transaction);
406
- });
425
+ const updated = await this.transaction((sql) => updateAttempt(sql, spec.table, { key, generation: row.generation_id, attempt }, 'status = ?, next_attempt_at = ?, last_error = ?, last_error_name = ?', decision.terminal ? 'failed' : 'pending', decision.nextAttemptAt, serializedError.message, serializedError.name));
407
426
  if (!updated) {
408
427
  return;
409
428
  }
429
+ if (decision.terminal) {
430
+ this.notify(spec.table, key);
431
+ }
410
432
  const settled = {
411
433
  ...spec.entity,
412
434
  type: 'attempt_settled',
@@ -426,7 +448,7 @@ export class Engine {
426
448
  }
427
449
  const engines = new WeakMap();
428
450
  /**
429
- * Owns the Durable Object's physical alarm, storage backend, and concurrency
451
+ * Owns the Durable Object's physical alarm, storage, and concurrency
430
452
  * pool so {@link Durability} and {@link DurabilityAlarms} can share them.
431
453
  *
432
454
  * Construct one per Durable Object when using both helpers, pass it to each,