@effect-agent/platform-cloudflare 0.1.0-beta.44 → 0.1.0-beta.45

package/src/alarm.ts

@@ -1,5 +1,4 @@
 import {
-  type ResolvedBinding,
   DurableAgentRuntime,
   SubmissionLedger,
   type DurableBindingFailure,
@@ -310,9 +309,7 @@ export class ThreadMaintenance extends Context.Service<
     ) => Effect.Effect<A, E | DurableAlarmError, R>;
   }
 >()("@effect-agent/platform-cloudflare/ThreadMaintenance") {
-  static readonly layer = (
-    bindings: ReadonlyArray<ResolvedBinding>,
-  ): Layer.Layer<
+  static readonly layer: Layer.Layer<
     ThreadMaintenance,
     never,
     | DurableAgentRuntime
@@ -322,288 +319,285 @@ export class ThreadMaintenance extends Context.Service<
     | CloudflareDurableRuntimeConfig
     | ThreadObjectIdentity
     | DurableObjectContext
-  > =>
-    Layer.effect(ThreadMaintenance)(
-      Effect.gen(function* () {
-        const runtime = yield* DurableAgentRuntime;
-        const ledger = yield* SubmissionLedger;
-        const alarm = yield* DurableAlarmService;
-        const config = yield* CloudflareDurableRuntimeConfig;
-        const identity = yield* ThreadObjectIdentity;
-        const { ctx } = yield* DurableObjectContext;
-        const failpoint = yield* ThreadMaintenanceFailpoint;
-
-        /**
-         * Consecutive no-progress passes — an in-memory CACHE, not state: a fresh incarnation
-         * restarts at zero and merely re-arms sooner than a long-lived one would have.
-         */
-        const stalls = yield* Ref.make(0);
-        /**
-         * Incarnation-local mutation count guarded with the generation transactions below. It is
-         * deliberately not durable: after eviction every begun mutation has stopped, while its
-         * pre-armed dirty generation remains durable for recovery. The short gate never spans the
-         * caller's mutation or cross-Object I/O.
-         */
-        const activeMutations = yield* Ref.make(0);
-        const generationGate = yield* Semaphore.make(1);
-        // At-least-once deliveries are idempotent, but overlapping pass bodies could otherwise
-        // acknowledge state while a sibling pass is still mutating it. Port/RPC mutations do not
-        // take this permit, so cross-Object I/O cannot deadlock the maintenance serialization.
-        const maintenancePassGate = yield* Semaphore.make(1);
-        const minimumAlarmDelay = Math.max(1, Math.ceil(config.alarmBackoffBase / 2));
-
-        const runTransaction = <A>(
-          operation: string,
-          transaction: () => Promise<A>,
-        ): Effect.Effect<A, DurableAlarmError> =>
-          Effect.tryPromise({
-            try: transaction,
-            catch: alarmFailure(operation),
-          });
-
-        const beginMutation = Effect.fn("ThreadMaintenance.beginMutation")(function* () {
-          yield* failpoint.hit("maintenance:dirty:before");
-          const now = yield* Clock.currentTimeMillis;
-
-          yield* runTransaction("advance maintenance generation", () =>
-            ctx.storage.transaction(async (transaction) => {
-              const { state } = await readMaintenanceState(transaction);
-
-              const next = ThreadMaintenanceState.make({
-                ...state,
-                dirty: state.dirty + 1n,
-              });
-
-              await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(next));
-              // The earliest configured retry bounds a newly actionable mutation without relying
-              // on its best-effort immediate wake hint.
-              await ensureTransactionAlarmBy(transaction, now + minimumAlarmDelay);
-            }),
-          );
-          yield* failpoint.hit("maintenance:dirty:after");
-          yield* Ref.update(activeMutations, (active) => active + 1);
+  > = Layer.effect(ThreadMaintenance)(
+    Effect.gen(function* () {
+      const runtime = yield* DurableAgentRuntime;
+      const ledger = yield* SubmissionLedger;
+      const alarm = yield* DurableAlarmService;
+      const config = yield* CloudflareDurableRuntimeConfig;
+      const identity = yield* ThreadObjectIdentity;
+      const { ctx } = yield* DurableObjectContext;
+      const failpoint = yield* ThreadMaintenanceFailpoint;
+
+      /**
+       * Consecutive no-progress passes — an in-memory CACHE, not state: a fresh incarnation
+       * restarts at zero and merely re-arms sooner than a long-lived one would have.
+       */
+      const stalls = yield* Ref.make(0);
+      /**
+       * Incarnation-local mutation count guarded with the generation transactions below. It is
+       * deliberately not durable: after eviction every begun mutation has stopped, while its
+       * pre-armed dirty generation remains durable for recovery. The short gate never spans the
+       * caller's mutation or cross-Object I/O.
+       */
+      const activeMutations = yield* Ref.make(0);
+      const generationGate = yield* Semaphore.make(1);
+      // At-least-once deliveries are idempotent, but overlapping pass bodies could otherwise
+      // acknowledge state while a sibling pass is still mutating it. Port/RPC mutations do not
+      // take this permit, so cross-Object I/O cannot deadlock the maintenance serialization.
+      const maintenancePassGate = yield* Semaphore.make(1);
+      const minimumAlarmDelay = Math.max(1, Math.ceil(config.alarmBackoffBase / 2));
+
+      const runTransaction = <A>(
+        operation: string,
+        transaction: () => Promise<A>,
+      ): Effect.Effect<A, DurableAlarmError> =>
+        Effect.tryPromise({
+          try: transaction,
+          catch: alarmFailure(operation),
         });
 
-        const endMutation = generationGate.withPermit(
-          Ref.update(activeMutations, (active) => Math.max(0, active - 1)),
-        );
+      const beginMutation = Effect.fn("ThreadMaintenance.beginMutation")(function* () {
+        yield* failpoint.hit("maintenance:dirty:before");
+        const now = yield* Clock.currentTimeMillis;
 
-        const withMutation = <A, E, R>(
-          body: Effect.Effect<A, E, R>,
-        ): Effect.Effect<A, E | DurableAlarmError, R> =>
-          Effect.acquireUseRelease(
-            generationGate.withPermit(beginMutation()),
-            () =>
-              failpoint.hit("maintenance:mutation:armed").pipe(
-                Effect.andThen(body),
-                Effect.tap(() => failpoint.hit("maintenance:mutation:finished")),
-              ),
-            () => endMutation,
-          );
+        yield* runTransaction("advance maintenance generation", () =>
+          ctx.storage.transaction(async (transaction) => {
+            const { state } = await readMaintenanceState(transaction);
 
-        const ensureAlarm = Effect.fn("ThreadMaintenance.ensureAlarm")(function* () {
-          yield* failpoint.hit("maintenance:ensure:before");
-          const now = yield* Clock.currentTimeMillis;
+            const next = ThreadMaintenanceState.make({
+              ...state,
+              dirty: state.dirty + 1n,
+            });
 
-          yield* runTransaction("ensure maintenance alarm", () =>
-            ctx.storage.transaction(async (transaction) => {
-              const { state, initialized } = await readMaintenanceState(transaction);
+            await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(next));
+            // The earliest configured retry bounds a newly actionable mutation without relying
+            // on its best-effort immediate wake hint.
+            await ensureTransactionAlarmBy(transaction, now + minimumAlarmDelay);
+          }),
+        );
+        yield* failpoint.hit("maintenance:dirty:after");
+        yield* Ref.update(activeMutations, (active) => active + 1);
+      });
+
+      const endMutation = generationGate.withPermit(
+        Ref.update(activeMutations, (active) => Math.max(0, active - 1)),
+      );
+
+      const withMutation = <A, E, R>(
+        body: Effect.Effect<A, E, R>,
+      ): Effect.Effect<A, E | DurableAlarmError, R> =>
+        Effect.acquireUseRelease(
+          generationGate.withPermit(beginMutation()),
+          () =>
+            failpoint.hit("maintenance:mutation:armed").pipe(
+              Effect.andThen(body),
+              Effect.tap(() => failpoint.hit("maintenance:mutation:finished")),
+            ),
+          () => endMutation,
+        );
 
-              if (!initialized) {
-                await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(state));
-              }
-              if (state.dirty > state.processed) {
-                await ensureTransactionAlarmBy(transaction, now + config.wakeScanInterval);
-              }
-            }),
-          );
-          yield* failpoint.hit("maintenance:ensure:after");
-        });
+      const ensureAlarm = Effect.fn("ThreadMaintenance.ensureAlarm")(function* () {
+        yield* failpoint.hit("maintenance:ensure:before");
+        const now = yield* Clock.currentTimeMillis;
+
+        yield* runTransaction("ensure maintenance alarm", () =>
+          ctx.storage.transaction(async (transaction) => {
+            const { state, initialized } = await readMaintenanceState(transaction);
+
+            if (!initialized) {
+              await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(state));
+            }
+            if (state.dirty > state.processed) {
+              await ensureTransactionAlarmBy(transaction, now + config.wakeScanInterval);
+            }
+          }),
+        );
+        yield* failpoint.hit("maintenance:ensure:after");
+      });
+
+      const beginPass = Effect.fn("ThreadMaintenance.beginPass")(function* () {
+        yield* failpoint.hit("maintenance:begin:before");
+        const now = yield* Clock.currentTimeMillis;
+
+        const result = yield* runTransaction("begin maintenance pass", () =>
+          ctx.storage.transaction(async (transaction) => {
+            const { state, initialized } = await readMaintenanceState(transaction);
+
+            if (!initialized) {
+              await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(state));
+            }
+            if (state.processed >= state.dirty) {
+              await transaction.deleteAlarm();
+
+              return { _tag: "CaughtUp" as const, nonterminal: state.nonterminal };
+            }
+            // Pre-arm the earliest retry before recovery. A successful finish may move this slot
+            // LATER to its bounded backoff, which does not cancel the running handler.
+            await ensureTransactionAlarmBy(transaction, now + minimumAlarmDelay);
+
+            return { _tag: "Actionable" as const, generation: state.dirty };
+          }),
+        );
 
-        const beginPass = Effect.fn("ThreadMaintenance.beginPass")(function* () {
-          yield* failpoint.hit("maintenance:begin:before");
-          const now = yield* Clock.currentTimeMillis;
+        yield* failpoint.hit("maintenance:begin:after");
 
-          const result = yield* runTransaction("begin maintenance pass", () =>
-            ctx.storage.transaction(async (transaction) => {
-              const { state, initialized } = await readMaintenanceState(transaction);
+        return result;
+      });
 
-              if (!initialized) {
-                await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(state));
-              }
-              if (state.processed >= state.dirty) {
-                await transaction.deleteAlarm();
+      const rearmDelay = Effect.fn("ThreadMaintenance.rearmDelay")(function* (progressed: boolean) {
+        const priorStalls = yield* Ref.getAndUpdate(stalls, (count) =>
+          progressed ? 0 : count + 1,
+        );
 
-                return { _tag: "CaughtUp" as const, nonterminal: state.nonterminal };
-              }
-              // Pre-arm the earliest retry before recovery. A successful finish may move this slot
-              // LATER to its bounded backoff, which does not cancel the running handler.
-              await ensureTransactionAlarmBy(transaction, now + minimumAlarmDelay);
+        if (progressed) return config.alarmBackoffBase;
+        const exponent = Math.min(priorStalls, 30);
+        const backoff = Math.min(config.alarmBackoffCap, config.alarmBackoffBase * 2 ** exponent);
+        const jitter = yield* Random.next;
+        // Full jitter over [backoff/2, backoff]: desynchronizes retry storms without ever
+        // waiting longer than the deterministic bound.
+        const jittered = Math.ceil(backoff / 2 + (backoff / 2) * jitter);
+
+        return Math.min(jittered, config.wakeScanInterval);
+      });
+
+      const pass = Effect.fn("ThreadMaintenance.pass")(function* (): Effect.fn.Return<
+        MaintenancePassReport,
+        MaintenancePassFailure
+      > {
+        const annotate = (report: MaintenancePassReport) =>
+          Effect.annotateCurrentSpan({
+            phase: report.phase,
+            recovered: report.recovered,
+            settled: report.settled,
+            nonterminal: report.nonterminal,
+            alarm: report.alarm,
+          }).pipe(Effect.as(report));
+
+        const started = yield* generationGate.withPermit(
+          Effect.gen(function* () {
+            const activeAtStart = yield* Ref.get(activeMutations);
+            const generation = yield* beginPass();
+
+            return { ...generation, activeAtStart };
+          }),
+        );
 
-              return { _tag: "Actionable" as const, generation: state.dirty };
+        if (started._tag === "CaughtUp") {
+          return yield* annotate(
+            MaintenancePassReport.make({
+              phase: "caught-up",
+              recovered: 0,
+              settled: 0,
+              nonterminal: started.nonterminal,
+              alarm: "cleared",
             }),
           );
-
-          yield* failpoint.hit("maintenance:begin:after");
-
-          return result;
+        }
+        // Step 2 — reconciliation strictly precedes new work in this pass (exit gate).
+        const recovered: ReadonlyArray<RecoveryReport> = yield* runtime.runRecovery;
+        // Step 3 — one bounded drain pass over this Object's own lane.
+        const settlements = yield* runtime.processThreadResolved(identity.threadId);
+        // Observe residual state before acknowledging this exact pass-start generation.
+        const remaining = yield* Stream.runCollect(ledger.scanNonterminal);
+        const reports = new Map(recovered.map((report) => [report.submissionId, report]));
+        const head = remaining[0];
+        const headWaiting = head !== undefined && stableExternalWait(head, reports);
+
+        const autonomous = remaining.some((snapshot, index) => {
+          // FIFO followers cannot execute through a stable external wait. Only plain queued
+          // input is dormant here; admission repairs and accepted aborts still need a pass.
+          if (
+            index > 0 &&
+            headWaiting &&
+            snapshot.state === "ready" &&
+            reports.get(snapshot.submissionId)?.decision._tag === "ApplyInput"
+          )
+            return false;
+
+          return !stableExternalWait(snapshot, reports);
         });
 
-        const rearmDelay = Effect.fn("ThreadMaintenance.rearmDelay")(function* (
-          progressed: boolean,
-        ) {
-          const priorStalls = yield* Ref.getAndUpdate(stalls, (count) =>
-            progressed ? 0 : count + 1,
-          );
+        const progressed =
+          settlements.length > 0 || recovered.some((report) => report.disposition === "repaired");
 
-          if (progressed) return config.alarmBackoffBase;
-          const exponent = Math.min(priorStalls, 30);
-          const backoff = Math.min(config.alarmBackoffCap, config.alarmBackoffBase * 2 ** exponent);
-          const jitter = yield* Random.next;
-          // Full jitter over [backoff/2, backoff]: desynchronizes retry storms without ever
-          // waiting longer than the deterministic bound.
-          const jittered = Math.ceil(backoff / 2 + (backoff / 2) * jitter);
+        const delay = autonomous ? yield* rearmDelay(progressed) : 0;
+        const now = yield* Clock.currentTimeMillis;
 
-          return Math.min(jittered, config.wakeScanInterval);
-        });
+        yield* failpoint.hit("maintenance:finish:before");
 
-        const pass = Effect.fn("ThreadMaintenance.pass")(function* (): Effect.fn.Return<
-          MaintenancePassReport,
-          MaintenancePassFailure
-        > {
-          const annotate = (report: MaintenancePassReport) =>
-            Effect.annotateCurrentSpan({
-              phase: report.phase,
-              recovered: report.recovered,
-              settled: report.settled,
-              nonterminal: report.nonterminal,
-              alarm: report.alarm,
-            }).pipe(Effect.as(report));
-
-          const started = yield* generationGate.withPermit(
-            Effect.gen(function* () {
-              const activeAtStart = yield* Ref.get(activeMutations);
-              const generation = yield* beginPass();
-
-              return { ...generation, activeAtStart };
-            }),
-          );
+        const alarmDisposition = yield* generationGate.withPermit(
+          Effect.gen(function* () {
+            const active = yield* Ref.get(activeMutations);
 
-          if (started._tag === "CaughtUp") {
-            return yield* annotate(
-              MaintenancePassReport.make({
-                phase: "caught-up",
-                recovered: 0,
-                settled: 0,
-                nonterminal: started.nonterminal,
-                alarm: "cleared",
-              }),
-            );
-          }
-          // Step 2 — reconciliation strictly precedes new work in this pass (exit gate).
-          const recovered: ReadonlyArray<RecoveryReport> = yield* runtime.runRecovery;
-          // Step 3 — one bounded drain pass over this Object's own lane.
-          const settlements = yield* runtime.processThreadResolved(identity.threadId, bindings);
-          // Observe residual state before acknowledging this exact pass-start generation.
-          const remaining = yield* Stream.runCollect(ledger.scanNonterminal);
-          const reports = new Map(recovered.map((report) => [report.submissionId, report]));
-          const head = remaining[0];
-          const headWaiting = head !== undefined && stableExternalWait(head, reports);
-
-          const autonomous = remaining.some((snapshot, index) => {
-            // FIFO followers cannot execute through a stable external wait. Only plain queued
-            // input is dormant here; admission repairs and accepted aborts still need a pass.
-            if (
-              index > 0 &&
-              headWaiting &&
-              snapshot.state === "ready" &&
-              reports.get(snapshot.submissionId)?.decision._tag === "ApplyInput"
-            )
-              return false;
-
-            return !stableExternalWait(snapshot, reports);
-          });
-
-          const progressed =
-            settlements.length > 0 || recovered.some((report) => report.disposition === "repaired");
-
-          const delay = autonomous ? yield* rearmDelay(progressed) : 0;
-          const now = yield* Clock.currentTimeMillis;
-
-          yield* failpoint.hit("maintenance:finish:before");
+            return yield* runTransaction("finish maintenance pass", () =>
+              ctx.storage.transaction(async (transaction) => {
+                const { state } = await readMaintenanceState(transaction);
 
-          const alarmDisposition = yield* generationGate.withPermit(
-            Effect.gen(function* () {
-              const active = yield* Ref.get(activeMutations);
-
-              return yield* runTransaction("finish maintenance pass", () =>
-                ctx.storage.transaction(async (transaction) => {
-                  const { state } = await readMaintenanceState(transaction);
-
-                  // Autonomous work and in-flight mutations intentionally leave the observed
-                  // generation dirty. Otherwise acknowledge only the pass-start generation.
-                  const processed =
-                    autonomous || started.activeAtStart > 0 || active > 0
+                // Autonomous work and in-flight mutations intentionally leave the observed
+                // generation dirty. Otherwise acknowledge only the pass-start generation.
+                const processed =
+                  autonomous || started.activeAtStart > 0 || active > 0
+                    ? state.processed
+                    : state.processed > started.generation
                       ? state.processed
-                      : state.processed > started.generation
-                        ? state.processed
-                        : started.generation;
-
-                  const next = ThreadMaintenanceState.make({
-                    ...state,
-                    processed,
-                    nonterminal: remaining.length,
-                  });
-
-                  await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(next));
-                  if (autonomous) {
-                    // Replace the crash-fallback slot with this pass's bounded backoff. The target
-                    // is never earlier than the begin-pass fallback, so workerd does not cancel
-                    // this running alarm handler before its report/span can complete.
-                    await transaction.setAlarm(now + delay);
-
-                    return "rearmed" as const;
-                  }
-                  if (started.activeAtStart > 0 || active > 0 || next.dirty > next.processed) {
-                    // A mutation overlapped this pass's observation window or raced
-                    // acknowledgement. It stays dirty and its pre-armed bounded alarm survives;
-                    // unseen effects are never acknowledged. Do not accelerate that future alarm
-                    // from inside the current handler: workerd cancels a running handler when it
-                    // writes an earlier slot.
-                    await ensureTransactionAlarmBy(transaction, now + config.wakeScanInterval);
-
-                    return "rearmed" as const;
-                  }
-                  await transaction.deleteAlarm();
-
-                  return "cleared" as const;
-                }),
-              );
-            }),
-          );
-
-          yield* failpoint.hit("maintenance:finish:after");
-          if (alarmDisposition === "cleared") {
-            yield* Ref.set(stalls, 0);
-          }
+                      : started.generation;
+
+                const next = ThreadMaintenanceState.make({
+                  ...state,
+                  processed,
+                  nonterminal: remaining.length,
+                });
+
+                await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(next));
+                if (autonomous) {
+                  // Replace the crash-fallback slot with this pass's bounded backoff. The target
+                  // is never earlier than the begin-pass fallback, so workerd does not cancel
+                  // this running alarm handler before its report/span can complete.
+                  await transaction.setAlarm(now + delay);
+
+                  return "rearmed" as const;
+                }
+                if (started.activeAtStart > 0 || active > 0 || next.dirty > next.processed) {
+                  // A mutation overlapped this pass's observation window or raced
+                  // acknowledgement. It stays dirty and its pre-armed bounded alarm survives;
+                  // unseen effects are never acknowledged. Do not accelerate that future alarm
+                  // from inside the current handler: workerd cancels a running handler when it
+                  // writes an earlier slot.
+                  await ensureTransactionAlarmBy(transaction, now + config.wakeScanInterval);
+
+                  return "rearmed" as const;
+                }
+                await transaction.deleteAlarm();
 
-          return yield* annotate(
-            MaintenancePassReport.make({
-              phase: "actionable",
-              recovered: recovered.length,
-              settled: settlements.length,
-              nonterminal: remaining.length,
-              alarm: alarmDisposition,
-            }),
-          );
-        });
+                return "cleared" as const;
+              }),
+            );
+          }),
+        );
 
-        return ThreadMaintenance.of({
-          // A mid-pass immediate hint is droppable; durable dirty state decides the final alarm.
-          pass: alarm.withWakesDeferred(maintenancePassGate.withPermit(pass())),
-          ensureAlarm: ensureAlarm(),
-          withMutation,
-        });
-      }),
-    );
+        yield* failpoint.hit("maintenance:finish:after");
+        if (alarmDisposition === "cleared") {
+          yield* Ref.set(stalls, 0);
+        }
+
+        return yield* annotate(
+          MaintenancePassReport.make({
+            phase: "actionable",
+            recovered: recovered.length,
+            settled: settlements.length,
+            nonterminal: remaining.length,
+            alarm: alarmDisposition,
+          }),
+        );
+      });
+
+      return ThreadMaintenance.of({
+        // A mid-pass immediate hint is droppable; durable dirty state decides the final alarm.
+        pass: alarm.withWakesDeferred(maintenancePassGate.withPermit(pass())),
+        ensureAlarm: ensureAlarm(),
+        withMutation,
+      });
+    }),
+  );
 }

package/src/layers.ts

@@ -70,7 +70,7 @@ import { cloudflareWakeSchedulerLayer } from "./wake-scheduler.ts";
 
 /**
  * Raw (unvalidated) construction options for `ThreadObject.make`, mirroring
- * `NodeDurableRuntimeOptions`. Optional fields default to the documented production values
+ * `NodeDurableAgentRuntimeOptions`. Optional fields default to the documented production values
  * (`CLOUDFLARE_RUNTIME_DEFAULTS`); everything is schema-decoded into
  * `CloudflareDurableRuntimeConfigValue` before any resource opens (deployment §5 gate 1).
  */
@@ -367,7 +367,7 @@ export const layerFromBindings = (
 
       const base = Layer.mergeAll(DurableAlarmService.layer, ProgressWaitRegistry.layer);
 
-      const runtimeStack = DurableAgentRuntime.layerWithServices.pipe(
+      const runtimeStack = DurableAgentRuntime.layerWithBindings(bindings).pipe(
         Layer.provideMerge(routedPorts),
         Layer.provideMerge(cloudflareWakeSchedulerLayer),
         Layer.provideMerge(base),
@@ -375,7 +375,7 @@ export const layerFromBindings = (
 
       return Layer.mergeAll(
         runtimeStack,
-        ThreadMaintenance.layer(bindings).pipe(Layer.provide(runtimeStack)),
+        ThreadMaintenance.layer.pipe(Layer.provide(runtimeStack)),
         portsEndpointLayer,
       );
     }),