@effect-agent/platform-cloudflare 0.1.0-beta.79 → 0.1.0-beta.80

package/src/Alarm.ts

@@ -1,3 +1,4 @@
+import { ThreadId } from "@effect-agent/core/Identifiers";
 import { type DurableBindingFailure } from "@effect-agent/thread/AgentRegistration";
 import {
   DurableAgentRuntime,
@@ -28,7 +29,7 @@ import {
   Stream,
 } from "effect";
 
-import { ThreadObjectIdentity, DurableObjectContext } from "./CloudflareBindings.ts";
+import { DurableObjectContext } from "./CloudflareBindings.ts";
 import { CloudflareDurableRuntimeConfig } from "./CloudflareConfig.ts";
 import { safeCauseMessage } from "./internal/boundary.ts";
 
@@ -188,6 +189,8 @@ export type ThreadMaintenanceFailpointLocation =
   | "maintenance:ensure:after"
   | "maintenance:begin:before"
   | "maintenance:begin:after"
+  | "maintenance:select:before"
+  | "maintenance:select:after"
   | "maintenance:finish:before"
   | "maintenance:finish:after";
 
@@ -255,6 +258,26 @@ export const ThreadMessageDelivery = Context.Reference<{
   defaultValue: () => ({ drain: Effect.void, pendingDeadline: Effect.succeed(Option.none()) }),
 });
 
+/**
+ * Application obligations sharing this Object's alarm. The deadline read is local and
+ * read-only. Drain beside the native Attempt and always finish one initial bounded wave,
+ * even when `finished` was already signalled. Then stop starting new waves on that signal
+ * and finish the bounded current wave before returning. Native maintenance joins that work
+ * before acknowledging a generation. Mutations use the same ThreadMutationGate; hooks never
+ * write the raw alarm slot. Pending host work does not defer a ready model Attempt.
+ */
+export const ThreadHostMaintenance = Context.Reference<{
+  readonly pendingDeadline: Effect.Effect<Option.Option<number>, DurableAlarmError>;
+  readonly drainUntil: (
+    finished: Deferred.Deferred<void>,
+  ) => Effect.Effect<void, DurableAlarmError>;
+}>("@effect-agent/platform-cloudflare/ThreadHostMaintenance", {
+  defaultValue: () => ({
+    pendingDeadline: Effect.succeed(Option.none()),
+    drainUntil: () => Effect.void,
+  }),
+});
+
 const earliestDeadline = (
   left: Option.Option<number>,
   right: Option.Option<number>,
@@ -290,6 +313,8 @@ class ThreadMaintenanceState extends Schema.Class<ThreadMaintenanceState>(
   dirty: MaintenanceGeneration,
   processed: MaintenanceGeneration,
   nonterminal: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  /** One physical-owner cursor; old single-lane records need no conversion. */
+  lastServedThreadId: Schema.optionalKey(ThreadId),
 }) {}
 
 const MAINTENANCE_STATE_KEY = "effect-agent:thread-maintenance:v1";
@@ -482,7 +507,6 @@ export class ThreadMaintenance extends Context.Service<
     | DurableAlarmService
     | ThreadMaintenanceFailpoint
     | CloudflareDurableRuntimeConfig
-    | ThreadObjectIdentity
     | DurableObjectContext
   > = Layer.effect(ThreadMaintenance)(
     Effect.gen(function* () {
@@ -490,7 +514,6 @@ export class ThreadMaintenance extends Context.Service<
       const ledger = yield* SubmissionLedger;
       const alarm = yield* DurableAlarmService;
       const config = yield* CloudflareDurableRuntimeConfig;
-      const identity = yield* ThreadObjectIdentity;
       const { ctx } = yield* DurableObjectContext;
       const failpoint = yield* ThreadMaintenanceFailpoint;
 
@@ -503,6 +526,7 @@ export class ThreadMaintenance extends Context.Service<
       const publication = yield* ThreadPublication;
       const projection = yield* ThreadProjectionMaintenance;
       const messages = yield* ThreadMessageDelivery;
+      const host = yield* ThreadHostMaintenance;
 
       // A broken disposable index still needs a retry alarm and must not prevent startup.
       const projectionDeadline = projection.pendingDeadline.pipe(
@@ -518,7 +542,7 @@ export class ThreadMaintenance extends Context.Service<
       const pendingDeadline = Effect.gen(function* () {
         return earliestDeadline(
           earliestDeadline(yield* publication.pendingDeadline, yield* messages.pendingDeadline),
-          yield* projectionDeadline,
+          earliestDeadline(yield* projectionDeadline, yield* host.pendingDeadline),
         );
       });
 
@@ -643,8 +667,13 @@ export class ThreadMaintenance extends Context.Service<
           messages.drainUntil?.(deliveryFinished) ?? messages.drain,
         );
 
+        const hostWork = yield* Effect.forkChild(host.drainUntil(deliveryFinished));
+
         const finishDelivery = Deferred.succeed(deliveryFinished, undefined).pipe(
-          Effect.andThen(Fiber.join(delivery)),
+          Effect.andThen(Fiber.awaitAll([delivery, hostWork])),
+          Effect.flatMap((outcomes) =>
+            Effect.forEach(outcomes, (outcome) => outcome, { discard: true }),
+          ),
         );
 
         // Capture derived-index failures until canonical work has had its turn. Interruption
@@ -717,24 +746,72 @@ export class ThreadMaintenance extends Context.Service<
         }
         // Step 2 — reconciliation strictly precedes new work in this pass (exit gate).
         const recovered: ReadonlyArray<RecoveryReport> = yield* runtime.runRecovery;
-        // One head Attempt per event. The runtime yields after a committed turn when the
-        // soft deadline is reached; queued followers belong to a subsequent alarm.
-        const settlement = yield* runtime.processThreadHead(identity.threadId, { yieldAfter });
+        const reports = new Map(recovered.map((report) => [report.submissionId, report]));
+        const current = yield* Stream.runCollect(ledger.scanNonterminal);
+        const heads = new Map<ThreadId, SubmissionSnapshot>();
+
+        for (const row of current) {
+          if (!heads.has(row.threadId)) heads.set(row.threadId, row);
+        }
+
+        const eligible = [...heads.values()]
+          .filter((head) => !stableExternalWait(head, reports))
+          .map((head) => head.threadId)
+          .sort();
+
+        let selected = eligible[0];
+
+        if (heads.size > 1 && selected !== undefined) {
+          yield* failpoint.hit("maintenance:select:before");
+          selected = yield* runTransaction("select maintenance lane", () =>
+            ctx.storage.transaction(async (transaction) => {
+              const { state } = await readMaintenanceState(transaction);
+
+              const next =
+                eligible.find(
+                  (threadId) =>
+                    state.lastServedThreadId === undefined || threadId > state.lastServedThreadId,
+                ) ?? eligible[0];
+
+              if (next !== undefined) {
+                // Persist before the Attempt so an eviction or repeated yield cannot
+                // monopolize the first lane. The generation and prearmed alarm survive.
+                await transaction.put(
+                  MAINTENANCE_STATE_KEY,
+                  encodeMaintenanceState(
+                    ThreadMaintenanceState.make({ ...state, lastServedThreadId: next }),
+                  ),
+                );
+              }
+
+              return next;
+            }),
+          );
+          yield* failpoint.hit("maintenance:select:after");
+        }
+
+        // One FIFO head per event, across all local lanes. The runtime keeps its normal
+        // bounded Attempt and recovery contracts; followers belong to another alarm.
+        const settlement =
+          selected === undefined
+            ? Option.none()
+            : yield* runtime.processThreadHead(selected, { yieldAfter });
 
         yield* finishDelivery;
         if (Exit.isFailure(projected)) return yield* Effect.failCause(projected.cause);
         // 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 waitingHeads = new Map<ThreadId, boolean>();
+
+        const autonomous = remaining.some((snapshot) => {
+          const headWaiting = waitingHeads.get(snapshot.threadId);
 
-        const autonomous = remaining.some((snapshot, index) => {
+          if (headWaiting === undefined)
+            waitingHeads.set(snapshot.threadId, stableExternalWait(snapshot, reports));
           // 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 &&
+            headWaiting === true &&
             snapshot.state === "ready" &&
             reports.get(snapshot.submissionId)?.decision._tag === "ApplyInput"
           )

package/src/CloudflareBindings.ts

@@ -52,15 +52,18 @@ export interface ThreadObjectRpc extends Rpc.DurableObjectBranded {
   wake(): Promise<void>;
 }
 
+/** A logical Thread endpoint may be bound to an application Object without forging its brand. */
+export type ThreadObjectClient = Omit<ThreadObjectRpc, keyof Rpc.DurableObjectBranded>;
+
 /**
- * The `DurableObjectNamespace` binding that addresses Thread Objects. The Object
- * identity rule is `namespace.idFromName(threadId)` (plan §1.2): Thread IDs are
- * globally unique, so the mapping is total and deterministic and no directory service exists.
+ * Deterministic logical Thread placement. The native adapter uses `idFromName(threadId)`;
+ * a shared application owner can bind that logical identity into its RPC adapter instead.
+ * Lookup performs no I/O and grants no authority. Every call resolves its target afresh.
  */
 export class ThreadObjectNamespace extends Context.Service<
   ThreadObjectNamespace,
   {
-    readonly namespace: DurableObjectNamespace<ThreadObjectRpc>;
+    readonly get: (threadId: ThreadId) => ThreadObjectClient;
     /** Stable binding name for opted-in native RPC tracing; absent by default. */
     readonly rpcTracing?: string;
   }
@@ -70,7 +73,7 @@ export class ThreadObjectNamespace extends Context.Service<
     options: { readonly rpcTracing?: string } = {},
   ): Layer.Layer<ThreadObjectNamespace> {
     return Layer.succeed(ThreadObjectNamespace)({
-      namespace,
+      get: (threadId) => namespace.get(namespace.idFromName(threadId)),
       ...(options.rpcTracing === undefined ? {} : { rpcTracing: options.rpcTracing }),
     });
   }
@@ -135,7 +138,7 @@ export const threadNamespaceLayer = (
 ): Layer.Layer<ThreadObjectNamespace, CloudflareBindingError> =>
   Layer.effect(ThreadObjectNamespace)(
     Effect.map(threadNamespaceFromEnv(env, binding), (namespace) => ({
-      namespace,
+      get: (threadId) => namespace.get(namespace.idFromName(threadId)),
       ...(options.rpcTracing === true ? { rpcTracing: binding } : {}),
     })),
   );
@@ -169,3 +172,9 @@ export class ThreadObjectIdentity extends Context.Service<
     readonly producerId: ProducerId;
   }
 >()("@effect-agent/platform-cloudflare/ThreadObjectIdentity") {}
+
+/** Logical Threads whose canonical stores and admission ledger live in this physical Object. */
+export class ThreadObjectPlacement extends Context.Service<
+  ThreadObjectPlacement,
+  { readonly ownsThread: (threadId: ThreadId) => boolean }
+>()("@effect-agent/platform-cloudflare/ThreadObjectPlacement") {}

package/src/CloudflareThreadClient.ts

@@ -445,12 +445,12 @@ export class CloudflareThreadClient extends Context.Service<
     ThreadObjectNamespace | Crypto.Crypto
   > = Layer.effect(CloudflareThreadClient)(
     Effect.gen(function* () {
-      const { namespace, rpcTracing } = yield* ThreadObjectNamespace;
+      const { get, rpcTracing } = yield* ThreadObjectNamespace;
       const crypto = yield* Crypto.Crypto;
 
       const call = Effect.fn(
         function* (
-          threadId: string,
+          threadId: ThreadId,
           operation: keyof typeof hostRpcMethods,
           encoded: unknown,
         ): Effect.fn.Return<HostResponse, ThreadClientError | HostProtocolError> {
@@ -460,7 +460,7 @@ export class CloudflareThreadClient extends Context.Service<
 
           const raw = yield* Effect.tryPromise({
             try: () => {
-              const stub = namespace.get(namespace.idFromName(threadId));
+              const stub = get(threadId);
 
               return stub[hostRpcMethods[operation]](encoded, ...traceArgs);
             },