effect-cf 0.50.0 → 0.52.0

package/src/DurableObjectAlarm.ts

@@ -19,15 +19,79 @@ CREATE TABLE IF NOT EXISTS effect_cf_scheduled_alarms (
   alarm_id TEXT NOT NULL,
   tag TEXT NOT NULL,
   run_at INTEGER NOT NULL,
+  wake_at INTEGER NOT NULL DEFAULT 0,
   repeat_every_ms INTEGER,
   payload TEXT NOT NULL
 );
-CREATE INDEX IF NOT EXISTS idx_effect_cf_scheduled_alarms_run_at_storage_id
-  ON effect_cf_scheduled_alarms (run_at, storage_id);
+CREATE TABLE IF NOT EXISTS effect_cf_alarm_attempts (
+  storage_id TEXT PRIMARY KEY,
+  revision TEXT NOT NULL,
+  attempts INTEGER NOT NULL,
+  parked INTEGER NOT NULL,
+  retry_at INTEGER,
+  progress INTEGER NOT NULL
+);
 `;
 
+const WAKE_INDEX = "idx_effect_cf_scheduled_alarms_wake_at_storage_id";
+
 const DEFAULT_PROCESS_DUE_ALARMS_LIMIT = 100;
-const DEFAULT_PROCESS_DUE_ALARMS_FAILURE_RESCHEDULE_AFTER = "30 seconds" satisfies Duration.Input;
+
+export const MIN_RETRY_DELAY_MS = 1_000;
+/** Default unchanged-attempt budget. */
+export const UNCHANGED_ATTEMPT_BUDGET = 8;
+/** Minimum and default parked recovery interval. */
+export const PARKED_RETRY_DELAY_MS = 3_600_000;
+
+/** Absolute product repeat floor. */
+export const MIN_REPEAT_INTERVAL_MS = 1_000;
+/** Default product schedule floor. Never use repeats to poll state. */
+export const DEFAULT_MIN_REPEAT_INTERVAL_MS = 60_000;
+
+export interface ScheduleConfiguration {
+  /** Retry floor, at least one second. Defaults to one second. */
+  readonly minimumRetryDelay?: Duration.Input;
+  /** Positive safe integer. Defaults to eight unchanged attempts. */
+  readonly unchangedAttemptBudget?: number;
+  /** Recovery interval, at least one hour and the retry floor. Defaults to one hour. */
+  readonly parkedRetryDelay?: Duration.Input;
+  /** Product repeat floor, at least one second. Defaults to one minute. */
+  readonly minimumRepeatInterval?: Duration.Input;
+}
+
+/** Optional policy overrides. Provide with Layer.succeed in the Durable Object's application layer. */
+export const ScheduleConfiguration = Context.Reference<ScheduleConfiguration>(
+  "effect-cf/DurableObjectAlarm/ScheduleConfiguration",
+  { defaultValue: () => ({}) },
+);
+
+const safeIntegerAtLeast = (minimum: number) =>
+  S.Int.check(S.isGreaterThanOrEqualTo(minimum), S.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
+
+const ScheduleConfigurationSchema = S.Struct({
+  minimumRetryDelay: safeIntegerAtLeast(MIN_RETRY_DELAY_MS),
+  unchangedAttemptBudget: safeIntegerAtLeast(1),
+  parkedRetryDelay: safeIntegerAtLeast(PARKED_RETRY_DELAY_MS),
+  minimumRepeatInterval: safeIntegerAtLeast(MIN_REPEAT_INTERVAL_MS),
+}).check(
+  S.makeFilter((configuration) =>
+    configuration.parkedRetryDelay >= configuration.minimumRetryDelay
+      ? undefined
+      : "parkedRetryDelay must be at least minimumRetryDelay",
+  ),
+);
+
+type ResolvedScheduleConfiguration = typeof ScheduleConfigurationSchema.Type;
+
+const retryDelay = (
+  attempts: number,
+  configuration: ResolvedScheduleConfiguration,
+  parked: boolean,
+  initialDelay = configuration.minimumRetryDelay,
+) =>
+  parked
+    ? configuration.parkedRetryDelay
+    : Math.min(configuration.parkedRetryDelay, initialDelay * 2 ** (attempts - 1));
 
 const getScheduledEventId = (input: { readonly id: string; readonly tag: string }) =>
   `effect-cf-alarm:${encodeURIComponent(input.tag)}:${encodeURIComponent(input.id)}`;
@@ -35,14 +99,47 @@ const getScheduledEventId = (input: { readonly id: string; readonly tag: string
 export type AlarmPayload = S.Json;
 
 interface AlarmRow extends Record<string, SqlStorageValue> {
+  readonly attempts: number;
   readonly alarm_id: string;
   readonly payload: string;
   readonly repeat_every_ms: number | null;
   readonly run_at: number;
+  readonly wake_at: number;
   readonly storage_id: string;
   readonly tag: string;
+  readonly revision: string;
+  readonly parked: number;
+  readonly retry_at: number | null;
+  readonly progress: number;
 }
 
+const alarmRowsSql = `
+  SELECT a.*, COALESCE(s.revision, '') AS revision,
+         COALESCE(s.attempts, 0) AS attempts, COALESCE(s.parked, 0) AS parked,
+         s.retry_at, COALESCE(s.progress, -1) AS progress
+    FROM effect_cf_scheduled_alarms a
+    LEFT JOIN effect_cf_alarm_attempts s USING (storage_id)`;
+
+const sameRevisionSql = `storage_id = ? AND COALESCE(
+  (SELECT revision FROM effect_cf_alarm_attempts WHERE storage_id = ?), '') = ?`;
+
+/** Content-free: no alarm identifiers, payload, error text or consumer state. */
+export const AlarmParked = S.TaggedStruct("AlarmParked", {
+  attempts: S.Int,
+  retryAt: S.DateTimeUtc,
+});
+export type AlarmParked = typeof AlarmParked.Type;
+
+/** Install with Layer.succeed / Effect.provideService. Reporting cannot undo a committed guard. */
+export const AlarmReporter = Context.Reference<(event: AlarmParked) => Effect.Effect<void>>(
+  "effect-cf/DurableObjectAlarm/AlarmReporter",
+  { defaultValue: () => (event) => Effect.logWarning(event) },
+);
+
+const CurrentAlarmPass = Context.Reference<
+  { readonly row: AlarmRow; readonly parked: AlarmParked[]; active: boolean } | undefined
+>("effect-cf/DurableObjectAlarm/CurrentAlarmPass", { defaultValue: () => undefined });
+
 interface NextAlarmRow extends Record<string, SqlStorageValue> {
   readonly run_at: number;
 }
@@ -81,6 +178,37 @@ export class InvalidProcessDueAlarmsOptionsError extends Data.TaggedError(
   }
 }
 
+export class InvalidScheduleConfigurationError extends Data.TaggedError(
+  "InvalidScheduleConfigurationError",
+)<{
+  readonly cause: unknown;
+}> {
+  override get message(): string {
+    return `Invalid Durable Object alarm configuration: ${ErrorMessage.causeMessage(this.cause)}`;
+  }
+}
+
+const getScheduleConfiguration = Effect.fnUntraced(function* (defaults: ScheduleConfiguration) {
+  const input = { ...defaults, ...(yield* ScheduleConfiguration) };
+
+  return yield* Effect.try({
+    try: () =>
+      S.decodeUnknownSync(ScheduleConfigurationSchema)({
+        minimumRetryDelay: Math.ceil(
+          Duration.toMillis(input.minimumRetryDelay ?? MIN_RETRY_DELAY_MS),
+        ),
+        unchangedAttemptBudget: input.unchangedAttemptBudget ?? UNCHANGED_ATTEMPT_BUDGET,
+        parkedRetryDelay: Math.ceil(
+          Duration.toMillis(input.parkedRetryDelay ?? PARKED_RETRY_DELAY_MS),
+        ),
+        minimumRepeatInterval: Math.ceil(
+          Duration.toMillis(input.minimumRepeatInterval ?? DEFAULT_MIN_REPEAT_INTERVAL_MS),
+        ),
+      }),
+    catch: (cause) => new InvalidScheduleConfigurationError({ cause }),
+  });
+});
+
 export class StoredAlarmDecodeError extends Data.TaggedError("StoredAlarmDecodeError")<{
   readonly cause: unknown;
   readonly storageId: string;
@@ -95,6 +223,7 @@ export type DurableObjectAlarmError =
   | InvalidAlarmRefError
   | InvalidProcessDueAlarmsOptionsError
   | InvalidRepeatEveryError
+  | InvalidScheduleConfigurationError
   | StorageOperationError
   | StoredAlarmDecodeError;
 
@@ -124,15 +253,18 @@ const decodeAlarmRef = (input: AlarmRef) =>
     Effect.mapError((cause) => new InvalidAlarmRefError({ cause })),
   );
 
-/** Reusing `{tag, id}` replaces an alarm. Repeats run after success, never as fixed-cadence catch-up. */
+/**
+ * Arm a logical deadline. External enrollment is progress; handler self-rearms consume a budget.
+ * Reusing `{tag, id}` replaces an alarm. Product repeats use the configured floor and run after completion.
+ */
 export type ScheduleAlarmInput<Tag extends string = string> = AlarmRef<Tag> & {
   readonly payload: AlarmPayload;
   readonly repeatEvery?: Duration.Input;
   readonly runAt: DateTime.Utc;
+  /** Optional monotonic source cursor. Only a strictly increasing cursor resets a live budget. */
+  readonly progress?: number;
 };
 
-export type ProcessDueAlarmsMode = "isolated" | "ordered";
-
 export interface ProcessDueAlarmsFailure {
   readonly cause: unknown;
   readonly event?: DurableObjectAlarmEvent;
@@ -144,15 +276,12 @@ export interface ProcessDueAlarmsFailure {
 export interface ProcessDueAlarmsResult {
   readonly failed: readonly ProcessDueAlarmsFailure[];
   readonly handled: readonly DurableObjectAlarmEvent[];
+  readonly parked: readonly AlarmParked[];
 }
 
 export type ProcessDueAlarmsFailureAction =
-  | "ordered"
   | "retry"
   | "skip-and-advance-repeat"
-  | {
-      readonly mode: "ordered";
-    }
   | {
       readonly mode: "retry";
       readonly retryFailedAfter?: Duration.Input;
@@ -163,8 +292,6 @@ export type ProcessDueAlarmsFailureAction =
 
 export interface ProcessDueAlarmsOptions<OnFailureR = never, OnFailureE = never> {
   readonly limit?: number;
-  /** `isolated` retries only the failed row; `ordered` stops before later rows. */
-  readonly mode?: ProcessDueAlarmsMode;
   readonly onFailure?: (
     failure: ProcessDueAlarmsFailure,
   ) => Effect.Effect<ProcessDueAlarmsFailureAction | void, OnFailureE, OnFailureR>;
@@ -179,7 +306,17 @@ export type ProcessDueAlarmsHandler<R = never, E = never> = (
  * Alarm mutations owned by one transaction callback. Run them in the callback's
  * fiber; forked work and use after the callback ends fail with StorageOperationError.
  */
-export type AlarmTransaction = Pick<AlarmScheduler, "scheduleAlarm" | "cancelAlarm">;
+export type AlarmTransaction = Pick<
+  AlarmScheduler,
+  "scheduleAlarm" | "scheduleAlarmEarlier" | "cancelAlarm"
+>;
+
+export interface AlarmStatus {
+  readonly attempts: number;
+  readonly parked: boolean;
+  readonly runAt: DateTime.Utc;
+  readonly retryAt: DateTime.Utc | undefined;
+}
 
 /** Own `storage.setAlarm()` exclusively: a Durable Object has one platform alarm timestamp. */
 export type AlarmScheduler = {
@@ -203,7 +340,15 @@ export type AlarmScheduler = {
     input: AlarmRef,
   ) => Effect.Effect<void, InvalidAlarmRefError | StorageOperationError>;
 
-  /** Acknowledge after handling. Conditional writes preserve handler replacements; alarms are at-least-once. */
+  /** Inspect retained work, including hourly recovery deadlines. */
+  readonly getAlarmStatus: (
+    input: AlarmRef,
+  ) => Effect.Effect<AlarmStatus | undefined, InvalidAlarmRefError | StorageOperationError>;
+
+  /**
+   * Dispatch by effective wake deadline, then storage key. Failures retry independently.
+   * Conditional acknowledgements preserve handler replacements; alarms are at-least-once.
+   */
   readonly processDueAlarms: <R = never, E = never, OnFailureR = never, OnFailureE = never>(
     handle: ProcessDueAlarmsHandler<R, E>,
     options?: ProcessDueAlarmsOptions<OnFailureR, OnFailureE>,
@@ -221,8 +366,11 @@ export type AlarmScheduler = {
     | InvalidAlarmPayloadError
     | InvalidAlarmRefError
     | InvalidRepeatEveryError
+    | InvalidScheduleConfigurationError
     | StorageOperationError
   >;
+  /** Atomically min-merge a logical deadline. Preserves an earlier alarm's payload and repeat. */
+  readonly scheduleAlarmEarlier: AlarmScheduler["scheduleAlarm"];
 };
 
 const StoredPayloadString = S.fromJsonString(S.Json);
@@ -237,10 +385,37 @@ const encodeStoredPayload = (payload: AlarmPayload) =>
     Effect.mapError((cause) => new InvalidAlarmPayloadError({ cause })),
   );
 
-const ensureTable = (state: DurableObjectState["Service"]) =>
-  state.storage.sql.exec(INIT_TABLE_SQL).pipe(Effect.asVoid);
+const ensureTable = Effect.fnUntraced(function* (state: DurableObjectState["Service"]) {
+  yield* state.storage.sql.exec(INIT_TABLE_SQL);
+  const index = yield* state.storage.sql.exec(
+    "SELECT name FROM sqlite_master WHERE type = 'index' AND name = ?",
+    WAKE_INDEX,
+  );
+
+  if ((yield* index.toArray()).length > 0) return;
+  const columns = yield* state.storage.sql.exec<{ name: string }>(
+    "SELECT name FROM pragma_table_info('effect_cf_scheduled_alarms')",
+  );
+  const names = new Set((yield* columns.toArray()).map((column) => column.name));
 
-const toRepeatEveryMillis = (input: Duration.Input | undefined) => {
+  if (!names.has("wake_at")) {
+    yield* state.storage.sql.exec(
+      "ALTER TABLE effect_cf_scheduled_alarms ADD COLUMN wake_at INTEGER NOT NULL DEFAULT 0",
+    );
+  }
+  // Backfill once, including retained schedules from before attempt tracking existed.
+  // The wake index is the durable migration marker and is created only after the backfill.
+  yield* state.storage.sql.exec(`UPDATE effect_cf_scheduled_alarms SET
+    wake_at = MAX(run_at, COALESCE((SELECT retry_at FROM effect_cf_alarm_attempts s
+      WHERE s.storage_id = effect_cf_scheduled_alarms.storage_id), run_at))`);
+  yield* state.storage.sql.exec(
+    "DROP INDEX IF EXISTS idx_effect_cf_scheduled_alarms_run_at_storage_id",
+  );
+  yield* state.storage.sql.exec(`CREATE INDEX IF NOT EXISTS ${WAKE_INDEX}
+    ON effect_cf_scheduled_alarms (wake_at, storage_id)`);
+});
+
+const toRepeatEveryMillis = (input: Duration.Input | undefined, minimum: number) => {
   if (input === undefined) {
     return Effect.succeed(null);
   }
@@ -249,8 +424,8 @@ const toRepeatEveryMillis = (input: Duration.Input | undefined) => {
     try: () => {
       const millis = Duration.toMillis(input);
 
-      if (!Number.isFinite(millis) || millis <= 0) {
-        throw new Error("Alarm repeatEvery must be a positive finite duration");
+      if (!Number.isFinite(millis) || millis < minimum) {
+        throw new Error(`Alarm repeatEvery must be at least ${minimum} milliseconds and finite`);
       }
 
       return Math.ceil(millis);
@@ -293,7 +468,7 @@ const getProcessLimit = (options: ProcessDueAlarmsOptions<unknown, unknown> | un
   return Effect.succeed(limit);
 };
 
-const toFailureRescheduleMillis = (input: Duration.Input) =>
+const toFailureRescheduleMillis = (input: Duration.Input, minimum: number) =>
   Effect.try({
     try: () => {
       const millis = Duration.toMillis(input);
@@ -302,14 +477,18 @@ const toFailureRescheduleMillis = (input: Duration.Input) =>
         throw new Error("Alarm failure rescheduleAfter must be a positive finite duration");
       }
 
-      return Math.ceil(millis);
+      return Math.max(minimum, Math.ceil(millis));
     },
     catch: (cause) => new InvalidProcessDueAlarmsOptionsError({ cause }),
   });
 
-const getFailureRetryDelay = (options: ProcessDueAlarmsOptions<unknown, unknown> | undefined) =>
+const getFailureRetryDelay = (
+  options: ProcessDueAlarmsOptions<unknown, unknown> | undefined,
+  configuration: ResolvedScheduleConfiguration,
+) =>
   toFailureRescheduleMillis(
-    options?.retryFailedAfter ?? DEFAULT_PROCESS_DUE_ALARMS_FAILURE_RESCHEDULE_AFTER,
+    options?.retryFailedAfter ?? configuration.minimumRetryDelay,
+    configuration.minimumRetryDelay,
   );
 
 const getFailureActionMode = (action: ProcessDueAlarmsFailureAction) =>
@@ -330,7 +509,7 @@ export const processDue = <R = never, E = never, OnFailureR = never, OnFailureE
 
 export type AlarmPayloadSchema = S.Codec<any, any, never, never>;
 
-export type AlarmFailurePolicy = "ordered" | "retry" | "skip-and-advance-repeat";
+export type AlarmFailurePolicy = "retry" | "skip-and-advance-repeat";
 
 export interface AlarmRetryPolicy {
   readonly initialDelay?: Duration.Input;
@@ -377,6 +556,7 @@ export interface DefinedAlarmTransaction<Definitions extends AlarmDefinitions> {
   readonly scheduleAlarm: (
     input: DefinedScheduleAlarmInput<Definitions>,
   ) => ReturnType<AlarmScheduler["scheduleAlarm"]>;
+  readonly scheduleAlarmEarlier: DefinedAlarmTransaction<Definitions>["scheduleAlarm"];
   readonly cancelAlarm: (
     input: AlarmRef<keyof Definitions & string>,
   ) => ReturnType<AlarmScheduler["cancelAlarm"]>;
@@ -397,6 +577,9 @@ export interface DefinedAlarmScheduler<
   Definitions extends AlarmDefinitions,
 > extends DefinedAlarmTransaction<Definitions> {
   readonly [TypedAlarmSchedulerTypeId]: typeof TypedAlarmSchedulerTypeId;
+  readonly getAlarmStatus: (
+    input: AlarmRef<keyof Definitions & string>,
+  ) => ReturnType<AlarmScheduler["getAlarmStatus"]>;
   readonly transaction: <A, E, R>(
     closure: (alarms: DefinedAlarmTransaction<Definitions>) => Effect.Effect<A, E, R>,
   ) => Effect.Effect<A, E | StorageOperationError, R>;
@@ -450,47 +633,54 @@ const makeDefinition = <const Definitions extends AlarmDefinitions>(definitions:
   const definitionFor = (tag: string) =>
     Object.hasOwn(definitions, tag) ? definitions[tag] : undefined;
 
-  const bind = (mutations: AlarmTransaction): DefinedAlarmTransaction<Definitions> => ({
-    scheduleAlarm: Effect.fn("DefinedAlarms.scheduleAlarm")(function* (
-      input: DefinedScheduleAlarmInput<Definitions>,
-    ) {
-      const definition = definitionFor(input.tag);
+  const bind = (mutations: AlarmTransaction): DefinedAlarmTransaction<Definitions> => {
+    const schedule = (method: "scheduleAlarm" | "scheduleAlarmEarlier") =>
+      Effect.fn("DefinedAlarms.scheduleAlarm")(function* (
+        input: DefinedScheduleAlarmInput<Definitions>,
+      ) {
+        const definition = definitionFor(input.tag);
 
-      if (definition === undefined) {
-        return yield* Effect.fail(
-          new InvalidAlarmRefError({
-            cause: new Error(`Unknown alarm tag "${input.tag}"`),
-          }),
+        if (definition === undefined) {
+          return yield* Effect.fail(
+            new InvalidAlarmRefError({
+              cause: new Error(`Unknown alarm tag "${input.tag}"`),
+            }),
+          );
+        }
+        const payload = yield* S.encodeEffect(getAlarmDefinitionSchema(definition))(
+          input.payload,
+        ).pipe(
+          Effect.flatMap(S.decodeUnknownEffect(S.Json)),
+          Effect.mapError((cause) => new InvalidAlarmPayloadError({ cause })),
         );
-      }
-      const payload = yield* S.encodeEffect(getAlarmDefinitionSchema(definition))(
-        input.payload,
-      ).pipe(
-        Effect.flatMap(S.decodeUnknownEffect(S.Json)),
-        Effect.mapError((cause) => new InvalidAlarmPayloadError({ cause })),
-      );
 
-      yield* mutations.scheduleAlarm({ ...input, payload });
-    }),
-    cancelAlarm: Effect.fn("DefinedAlarms.cancelAlarm")(function* (
-      input: AlarmRef<keyof Definitions & string>,
-    ) {
-      if (definitionFor(input.tag) === undefined) {
-        return yield* Effect.fail(
-          new InvalidAlarmRefError({
-            cause: new Error(`Unknown alarm tag "${input.tag}"`),
-          }),
-        );
-      }
+        yield* mutations[method]({ ...input, payload });
+      });
 
-      yield* mutations.cancelAlarm(input);
-    }),
-  });
+    return {
+      scheduleAlarm: schedule("scheduleAlarm"),
+      scheduleAlarmEarlier: schedule("scheduleAlarmEarlier"),
+      cancelAlarm: Effect.fn("DefinedAlarms.cancelAlarm")(function* (
+        input: AlarmRef<keyof Definitions & string>,
+      ) {
+        if (definitionFor(input.tag) === undefined) {
+          return yield* Effect.fail(
+            new InvalidAlarmRefError({
+              cause: new Error(`Unknown alarm tag "${input.tag}"`),
+            }),
+          );
+        }
+
+        yield* mutations.cancelAlarm(input);
+      }),
+    };
+  };
 
   return {
     make: (alarms: AlarmScheduler): DefinedAlarmScheduler<Definitions> => ({
       [TypedAlarmSchedulerTypeId]: TypedAlarmSchedulerTypeId,
       ...bind(alarms),
+      getAlarmStatus: (input) => alarms.getAlarmStatus(input),
       transaction: (closure) => alarms.transaction((tx) => closure(bind(tx))),
     }),
     handlers: <R = never, E = never>(
@@ -580,138 +770,189 @@ export class DurableObjectAlarm extends Context.Service<DurableObjectAlarm, Alar
     DurableObjectAlarm,
     Effect.gen(function* () {
       const state = yield* DurableObjectState;
+      const configurationDefaults = { ...(yield* ScheduleConfiguration) };
+
+      const readRow = Effect.fnUntraced(function* (storageId: string) {
+        const cursor = yield* state.storage.sql.exec<AlarmRow>(
+          `${alarmRowsSql} WHERE a.storage_id = ?`,
+          storageId,
+        );
+
+        return (yield* cursor.toArray())[0];
+      });
 
       const reconcileAlarm = Effect.fn("DurableObjectAlarm.reconcileAlarm")(function* () {
         const cursor = yield* state.storage.sql.exec<NextAlarmRow>(
-          `SELECT run_at FROM effect_cf_scheduled_alarms ORDER BY run_at ASC, storage_id ASC LIMIT 1`,
+          `SELECT wake_at AS run_at FROM effect_cf_scheduled_alarms
+            ORDER BY wake_at, storage_id LIMIT 1`,
         );
         const next = (yield* cursor.toArray())[0];
 
-        if (next === undefined) {
-          yield* state.storage.deleteAlarm();
-
-          return;
-        }
-
-        yield* state.storage.setAlarm(next.run_at);
+        // The scheduler is the sole alarm writer. Raw storage is confined to this boundary.
+        yield* Effect.tryPromise({
+          try: () =>
+            next === undefined
+              ? state.raw.storage.deleteAlarm()
+              : state.raw.storage.setAlarm(next.run_at),
+          catch: (cause) =>
+            new StorageOperationError({
+              operation: next === undefined ? "deleteAlarm" : "setAlarm",
+              cause,
+            }),
+        });
       });
 
-      const rescheduleFailedAlarm = Effect.fn("DurableObjectAlarm.rescheduleFailedAlarm")(
-        function* (row: AlarmRow, retryDelayMillis: number) {
-          const retryAt = (yield* Clock.currentTimeMillis) + retryDelayMillis;
-
-          if (row.repeat_every_ms === null) {
-            const cursor = yield* state.storage.sql.exec(
-              `UPDATE effect_cf_scheduled_alarms
-                  SET run_at = ?
-                WHERE storage_id = ?
-                  AND run_at = ?
-                  AND repeat_every_ms IS NULL
-                  AND payload = ?`,
-              retryAt,
-              row.storage_id,
-              row.run_at,
-              row.payload,
-            );
-
-            yield* cursor.rowsWritten;
-
-            return;
-          }
-
-          const cursor = yield* state.storage.sql.exec(
-            `UPDATE effect_cf_scheduled_alarms
-                SET run_at = ?
-              WHERE storage_id = ?
-                AND run_at = ?
-                AND repeat_every_ms = ?
-                AND payload = ?`,
-            retryAt,
-            row.storage_id,
-            row.run_at,
-            row.repeat_every_ms,
-            row.payload,
-          );
-
-          yield* cursor.rowsWritten;
-        },
-      );
-
-      const acknowledgeAlarm = Effect.fn("DurableObjectAlarm.acknowledgeAlarm")(function* (
-        row: AlarmRow,
+      const writeAttempts = Effect.fnUntraced(function* (
+        storageId: string,
+        attempts: number,
+        parked: number,
+        retryAt: number | null,
+        progress: number,
       ) {
-        if (row.repeat_every_ms === null) {
-          const cursor = yield* state.storage.sql.exec(
-            `DELETE FROM effect_cf_scheduled_alarms
-              WHERE storage_id = ?
-                AND run_at = ?
-                AND repeat_every_ms IS NULL
-                AND payload = ?`,
-            row.storage_id,
-            row.run_at,
-            row.payload,
-          );
-
-          yield* cursor.rowsWritten;
-
-          return;
-        }
-
-        const acknowledgedAt = yield* Clock.currentTimeMillis;
-        const cursor = yield* state.storage.sql.exec(
+        yield* state.storage.sql.exec(
+          `INSERT OR REPLACE INTO effect_cf_alarm_attempts
+            (storage_id, revision, attempts, parked, retry_at, progress)
+           VALUES (?, ?, ?, ?, ?, ?)`,
+          storageId,
+          crypto.randomUUID(),
+          attempts,
+          parked,
+          retryAt,
+          progress,
+        );
+        // Materialize the effective wake in the same transaction for indexed dispatch/reconciliation.
+        yield* state.storage.sql.exec(
           `UPDATE effect_cf_scheduled_alarms
-              SET run_at = ?
-            WHERE storage_id = ?
-              AND run_at = ?
-              AND repeat_every_ms = ?
-              AND payload = ?`,
-          acknowledgedAt + row.repeat_every_ms,
-          row.storage_id,
-          row.run_at,
-          row.repeat_every_ms,
-          row.payload,
+            SET wake_at = MAX(run_at, COALESCE(?, run_at))
+            WHERE storage_id = ?`,
+          retryAt,
+          storageId,
         );
-
-        yield* cursor.rowsWritten;
       });
 
       const cancelAlarm = Effect.fn("DurableObjectAlarm.cancelAlarm")(function* (input: AlarmRef) {
         const ref = yield* decodeAlarmRef(input);
+        const storageId = getScheduledEventId(ref);
 
         yield* state.storage.sql.exec(
           `DELETE FROM effect_cf_scheduled_alarms WHERE storage_id = ?`,
-          getScheduledEventId(ref),
+          storageId,
+        );
+        yield* state.storage.sql.exec(
+          `DELETE FROM effect_cf_alarm_attempts WHERE storage_id = ?`,
+          storageId,
         );
       });
 
       const scheduleAlarm = Effect.fn("DurableObjectAlarm.scheduleAlarm")(function* (
         input: ScheduleAlarmInput,
+        earlier: boolean,
+        reports: string[],
       ) {
+        const configuration = yield* getScheduleConfiguration(configurationDefaults);
         const ref = yield* decodeAlarmRef(input);
-        const repeatEveryMillis = yield* toRepeatEveryMillis(input.repeatEvery);
+        const repeatEveryMillis = yield* toRepeatEveryMillis(
+          input.repeatEvery,
+          configuration.minimumRepeatInterval,
+        );
         const payload = yield* encodeStoredPayload(input.payload);
+        const storageId = getScheduledEventId(ref);
+        const existing = yield* readRow(storageId);
+        const pass = yield* CurrentAlarmPass;
+        const source = pass?.row;
+        const progress = existing?.progress ?? source?.progress ?? -1;
+
+        if (pass !== undefined && !pass.active) {
+          return yield* Effect.fail(
+            new StorageOperationError({
+              operation: "alarm.schedule",
+              cause: new Error(
+                "Alarm handlers cannot schedule detached work after their pass ends",
+              ),
+            }),
+          );
+        }
+        if (input.progress !== undefined) {
+          yield* S.decodeUnknownEffect(S.Natural)(input.progress).pipe(
+            Effect.mapError((cause) => new InvalidAlarmRefError({ cause })),
+          );
+        }
+        // Replayed source notices cannot refill a live lane's budget or replace newer state.
+        if (source === undefined && input.progress !== undefined && input.progress <= progress) {
+          return;
+        }
+        const progressed = input.progress !== undefined && input.progress > progress;
+        const sourceProgressed =
+          source !== undefined && storageId === source.storage_id && progress > source.progress;
+        const attempts =
+          source === undefined || progressed || sourceProgressed
+            ? 0
+            : source.parked === 1 || existing?.parked === 1
+              ? Math.max(source.attempts, existing?.attempts ?? 0)
+              : Math.min(
+                  configuration.unchangedAttemptBudget,
+                  Math.max(source.attempts + 1, existing?.attempts ?? 0),
+                );
+        const parked =
+          attempts > 0 &&
+          (attempts >= configuration.unchangedAttemptBudget ||
+            source?.parked === 1 ||
+            existing?.parked === 1)
+            ? 1
+            : 0;
+        const now = yield* Clock.currentTimeMillis;
+        const retryAt =
+          attempts === 0 ? null : now + retryDelay(attempts, configuration, parked === 1);
         const runAt = DateTime.toEpochMillis(input.runAt);
+        const keepEarlier = earlier && existing !== undefined && existing.run_at <= runAt;
+        const scheduledAt = keepEarlier ? existing.run_at : runAt;
+        const scheduledPayload = keepEarlier ? existing.payload : payload;
+        const scheduledRepeat = keepEarlier ? existing.repeat_every_ms : repeatEveryMillis;
+        const nextProgress = Math.max(progress, input.progress ?? -1);
 
         yield* state.storage.sql.exec(
           `INSERT OR REPLACE INTO effect_cf_scheduled_alarms
-                   (storage_id, alarm_id, tag, run_at, repeat_every_ms, payload)
-                 VALUES (?, ?, ?, ?, ?, ?)`,
-          getScheduledEventId(ref),
+            (storage_id, alarm_id, tag, run_at, repeat_every_ms, payload)
+           VALUES (?, ?, ?, ?, ?, ?)`,
+          storageId,
           ref.id,
           ref.tag,
-          runAt,
-          repeatEveryMillis,
-          payload,
+          scheduledAt,
+          scheduledRepeat,
+          scheduledPayload,
         );
+        yield* writeAttempts(storageId, attempts, parked, retryAt, nextProgress);
+        if (parked === 1 && retryAt !== null && (existing?.parked ?? source?.parked ?? 0) === 0) {
+          reports.push(storageId);
+        }
+      });
+
+      const reportParked = Effect.fnUntraced(function* (storageIds: readonly string[]) {
+        if (storageIds.length === 0) return;
+        const pass = yield* CurrentAlarmPass;
+        const report = yield* AlarmReporter;
+
+        for (const storageId of new Set(storageIds)) {
+          const row = yield* readRow(storageId);
+
+          // Cancellation or progress later in the same transaction removes tentative parking.
+          if (row === undefined || row.parked === 0 || row.retry_at === null) continue;
+          const event = AlarmParked.make({
+            attempts: row.attempts,
+            retryAt: DateTime.makeUnsafe(Math.max(row.run_at, row.retry_at)),
+          });
+
+          pass?.parked.push(event);
+          // Reporting is at-most-once per parked episode, after the native commit.
+          yield* Effect.exit(Effect.suspend(() => report(event)));
+        }
       });
 
-      const transaction: AlarmScheduler["transaction"] = (closure) =>
-        state.storage.transaction(() =>
+      const transaction: AlarmScheduler["transaction"] = Effect.fnUntraced(function* (closure) {
+        const reports: string[] = [];
+        const result = yield* state.storage.transaction(() =>
           Effect.withFiber((owner) => {
             let active = true;
-
-            // A callback-owned handle cannot escape via a returned Effect or a
-            // detached fiber and write after reconciliation or rollback.
             const requireActive = <A, E>(effect: Effect.Effect<A, E>) =>
               Effect.withFiber<A, E | StorageOperationError>((fiber) =>
                 active && fiber === owner
@@ -731,7 +972,9 @@ export class DurableObjectAlarm extends Context.Service<DurableObjectAlarm, Alar
               const result = yield* Effect.suspend(() =>
                 closure({
                   cancelAlarm: (input) => requireActive(cancelAlarm(input)),
-                  scheduleAlarm: (input) => requireActive(scheduleAlarm(input)),
+                  scheduleAlarm: (input) => requireActive(scheduleAlarm(input, false, reports)),
+                  scheduleAlarmEarlier: (input) =>
+                    requireActive(scheduleAlarm(input, true, reports)),
                 }),
               ).pipe(
                 Effect.ensuring(
@@ -748,6 +991,72 @@ export class DurableObjectAlarm extends Context.Service<DurableObjectAlarm, Alar
           }),
         );
 
+        yield* reportParked(reports);
+
+        return result;
+      });
+
+      const rescheduleFailedAlarm = Effect.fnUntraced(function* (
+        row: AlarmRow,
+        initialDelay: number,
+        configuration: ResolvedScheduleConfiguration,
+        reports: string[],
+      ) {
+        const current = yield* readRow(row.storage_id);
+
+        // A self-rearm already charged this pass; a newer schedule must survive a stale failure.
+        if (current === undefined || current.revision !== row.revision) return;
+        const attempts =
+          row.parked === 1
+            ? row.attempts
+            : Math.min(configuration.unchangedAttemptBudget, row.attempts + 1);
+        const parked = row.parked === 1 || attempts >= configuration.unchangedAttemptBudget ? 1 : 0;
+        const retryAt =
+          (yield* Clock.currentTimeMillis) +
+          retryDelay(attempts, configuration, parked === 1, initialDelay);
+
+        yield* writeAttempts(row.storage_id, attempts, parked, retryAt, row.progress);
+        if (parked === 1 && row.parked === 0) {
+          reports.push(row.storage_id);
+        }
+      });
+
+      const acknowledgeAlarm = Effect.fnUntraced(function* (
+        row: AlarmRow,
+        configuration: ResolvedScheduleConfiguration,
+      ) {
+        if (row.repeat_every_ms === null) {
+          const cursor = yield* state.storage.sql.exec(
+            `DELETE FROM effect_cf_scheduled_alarms WHERE ${sameRevisionSql}`,
+            row.storage_id,
+            row.storage_id,
+            row.revision,
+          );
+
+          if ((yield* cursor.rowsWritten) > 0) {
+            yield* state.storage.sql.exec(
+              `DELETE FROM effect_cf_alarm_attempts WHERE storage_id = ?`,
+              row.storage_id,
+            );
+          }
+
+          return;
+        }
+        const now = yield* Clock.currentTimeMillis;
+        const cursor = yield* state.storage.sql.exec(
+          `UPDATE effect_cf_scheduled_alarms SET run_at = ? WHERE ${sameRevisionSql}`,
+          now + Math.max(configuration.minimumRepeatInterval, row.repeat_every_ms),
+          row.storage_id,
+          row.storage_id,
+          row.revision,
+        );
+
+        if ((yield* cursor.rowsWritten) > 0) {
+          // A completed product occurrence is progress. Missed occurrences are never replayed.
+          yield* writeAttempts(row.storage_id, 0, 0, null, row.progress);
+        }
+      });
+
       const processDueAlarms = Effect.fn("DurableObjectAlarm.processDueAlarms")(function* <
         R,
         E,
@@ -757,24 +1066,25 @@ export class DurableObjectAlarm extends Context.Service<DurableObjectAlarm, Alar
         handle: ProcessDueAlarmsHandler<R, E>,
         options?: ProcessDueAlarmsOptions<OnFailureR, OnFailureE>,
       ) {
+        const configuration = yield* getScheduleConfiguration(configurationDefaults);
+
         yield* ensureTable(state);
-        const mode = options?.mode ?? "isolated";
         const limit = yield* getProcessLimit(options);
+        const initialDelay = yield* getFailureRetryDelay(options, configuration);
         const now = yield* Clock.currentTimeMillis;
+
         const cursor = yield* state.storage.sql.exec<AlarmRow>(
-          `SELECT storage_id, alarm_id, tag, run_at, repeat_every_ms, payload
-             FROM effect_cf_scheduled_alarms
-            WHERE run_at <= ?
-            ORDER BY run_at ASC, storage_id ASC
-            LIMIT ?`,
+          `${alarmRowsSql}
+            WHERE a.wake_at <= ? ORDER BY a.wake_at ASC, a.storage_id ASC LIMIT ?`,
           now,
           limit,
         );
         const dueRows = yield* cursor.toArray();
         const handled: DurableObjectAlarmEvent[] = [];
         const failed: ProcessDueAlarmsFailure[] = [];
+        const parked: AlarmParked[] = [];
 
-        const handleFailure = function* (
+        const handleFailure = Effect.fnUntraced(function* (
           row: AlarmRow,
           event: DurableObjectAlarmEvent | undefined,
           cause: unknown,
@@ -788,72 +1098,96 @@ export class DurableObjectAlarm extends Context.Service<DurableObjectAlarm, Alar
           };
 
           failed.push(failure);
-          const failureAction =
-            options?.onFailure === undefined ? undefined : yield* options.onFailure(failure);
-          const actionMode =
-            failureAction === undefined ? mode : getFailureActionMode(failureAction);
-
-          if (actionMode === "retry" || actionMode === "isolated") {
-            const actionRetryDelay =
-              failureAction === undefined ? undefined : getFailureActionRetryDelay(failureAction);
-            const retryDelay =
-              actionRetryDelay === undefined
-                ? yield* getFailureRetryDelay(options)
-                : yield* toFailureRescheduleMillis(actionRetryDelay);
-
-            yield* rescheduleFailedAlarm(row, retryDelay);
-
-            return "continue" as const;
-          }
-
-          if (actionMode === "skip-and-advance-repeat") {
-            yield* acknowledgeAlarm(row);
+          const actionExit = yield* Effect.exit(
+            options?.onFailure === undefined
+              ? Effect.void
+              : Effect.suspend(() => options.onFailure!(failure)),
+          );
+          const action = Exit.isSuccess(actionExit) ? actionExit.value : undefined;
+          const actionMode = action === undefined ? "retry" : getFailureActionMode(action);
+          const delayInput = action === undefined ? undefined : getFailureActionRetryDelay(action);
+          const delayExit = yield* Effect.exit(
+            delayInput === undefined
+              ? Effect.succeed(initialDelay)
+              : toFailureRescheduleMillis(delayInput, configuration.minimumRetryDelay),
+          );
+          const delay = Exit.isSuccess(delayExit) ? delayExit.value : initialDelay;
+          const reports: string[] = [];
 
-            return "continue" as const;
+          yield* transaction(() =>
+            actionMode === "skip-and-advance-repeat"
+              ? acknowledgeAlarm(row, configuration)
+              : rescheduleFailedAlarm(row, delay, configuration, reports),
+          );
+          yield* reportParked(reports);
+          if (Exit.isFailure(actionExit)) {
+            return yield* Effect.failCause(actionExit.cause);
           }
-
-          yield* reconcileAlarm();
-
-          return "stop" as const;
-        };
+          if (Exit.isFailure(delayExit)) {
+            return yield* Effect.failCause(delayExit.cause);
+          }
+        });
 
         for (const row of dueRows) {
+          const current = yield* readRow(row.storage_id);
+
+          if (current === undefined || current.revision !== row.revision) {
+            continue;
+          }
+          const inPass = <A, E, R>(effect: Effect.Effect<A, E, R>) => {
+            const pass = { row, parked, active: true };
+
+            return effect.pipe(
+              Effect.provideService(CurrentAlarmPass, pass),
+              Effect.ensuring(
+                Effect.sync(() => {
+                  pass.active = false;
+                }),
+              ),
+            );
+          };
           const eventExit = yield* Effect.exit(toAlarmDue(row));
 
           if (Exit.isFailure(eventExit)) {
-            const action = yield* handleFailure(row, undefined, eventExit.cause);
-
-            if (action === "stop") {
-              return yield* Effect.failCause(eventExit.cause);
-            }
+            yield* inPass(handleFailure(row, undefined, eventExit.cause));
             continue;
           }
-
           const event = eventExit.value;
-          const handleExit = yield* Effect.exit(handle(event));
+          const handleExit = yield* Effect.exit(inPass(Effect.suspend(() => handle(event))));
 
           if (Exit.isFailure(handleExit)) {
-            const action = yield* handleFailure(row, event, handleExit.cause);
-
-            if (action === "stop") {
-              return yield* Effect.failCause(handleExit.cause);
-            }
+            yield* inPass(handleFailure(row, event, handleExit.cause));
             continue;
           }
-
-          yield* acknowledgeAlarm(row);
+          yield* transaction(() => acknowledgeAlarm(row, configuration));
           handled.push(event);
         }
+        yield* transaction(() => Effect.void);
 
-        yield* reconcileAlarm();
-
-        return { failed, handled };
+        return { failed, handled, parked };
       });
 
       return DurableObjectAlarm.of({
         cancelAlarm: (input) => transaction((alarms) => alarms.cancelAlarm(input)),
+        getAlarmStatus: Effect.fnUntraced(function* (input) {
+          const ref = yield* decodeAlarmRef(input);
+
+          yield* ensureTable(state);
+          const row = yield* readRow(getScheduledEventId(ref));
+
+          return row === undefined
+            ? undefined
+            : {
+                attempts: row.attempts,
+                parked: row.parked === 1,
+                runAt: DateTime.makeUnsafe(row.run_at),
+                retryAt: row.retry_at === null ? undefined : DateTime.makeUnsafe(row.retry_at),
+              };
+        }),
         processDueAlarms,
         scheduleAlarm: (input) => transaction((alarms) => alarms.scheduleAlarm(input)),
+        scheduleAlarmEarlier: (input) =>
+          transaction((alarms) => alarms.scheduleAlarmEarlier(input)),
         transaction,
       });
     }),