@yielded/agent-platform-cloudflare 0.0.0-stage → 0.1.0-beta.166

package/src/internal/message-delivery.ts

@@ -0,0 +1,120 @@
+import { type ThreadId } from "@yielded/agent/identifiers";
+import {
+  MessageDeliveryDriver,
+  MessageDeliveryError,
+  MessageDeliveryStore,
+} from "@yielded/agent/message-delivery";
+import { WakeScheduler } from "@yielded/agent/wake-scheduler";
+import { Clock, Context, Effect, Layer, Option } from "effect";
+
+import { DurableAlarmError, ThreadMessageDelivery, ThreadMutationGate } from "../Alarm.ts";
+import { ThreadObjectPlacement } from "../CloudflareBindings.ts";
+import * as DueQueue from "./due-queue.ts";
+
+/** Every write prearms its owner; the delivery due index owns its recovery deadline. */
+export const guardedMessageDeliveryStoreLayer = Layer.effect(
+  MessageDeliveryStore,
+  Effect.gen(function* () {
+    const store = yield* MessageDeliveryStore;
+    const mutations = yield* ThreadMutationGate;
+    const wakes = yield* WakeScheduler;
+    const { ownsThread } = yield* ThreadObjectPlacement;
+
+    const local = <A, E>(
+      owner: ThreadId | undefined,
+      body: Effect.Effect<A, E>,
+    ): Effect.Effect<A, E | MessageDeliveryError> =>
+      owner === undefined || ownsThread(owner)
+        ? body
+        : Effect.fail(
+            MessageDeliveryError.make({ reason: "validation", operation: "message owner" }),
+          );
+
+    const mutate = <A, E>(body: Effect.Effect<A, E>) =>
+      mutations
+        .withMutation(body, {
+          invalidatesRecovery: false,
+          lanes: [
+            DueQueue.Messages,
+            ...(store.lifecyclePublications === undefined ? [] : [DueQueue.Lifecycle]),
+          ],
+        })
+        .pipe(
+          Effect.catchTag("DurableAlarmError", (cause) =>
+            MessageDeliveryError.make({
+              reason: "storage",
+              operation: "prearm message delivery",
+              cause,
+            }),
+          ),
+        );
+
+    return MessageDeliveryStore.of({
+      limits: store.limits,
+      maxStoredValueBytes: store.maxStoredValueBytes,
+      insert: (record) =>
+        local(
+          record.key.ownerThreadId,
+          mutate(store.insert(record)).pipe(
+            Effect.tap(() => wakes.notify(record.key.ownerThreadId)),
+          ),
+        ),
+      get: (key) => local(key.ownerThreadId, store.get(key)),
+      list: (request) => local(request.ownerThreadId, store.list(request)),
+      change: (key, change) => local(key.ownerThreadId, mutate(store.change(key, change))),
+      // Only the trusted physical-owner selection omits an owner. All returned keys still
+      // pass placement validation before the driver may dispatch any of the wave.
+      due: (nowMillis, limit, owner) =>
+        local(owner, store.due(nowMillis, limit, owner)).pipe(
+          Effect.filterOrFail(
+            (keys) => keys.every((key) => ownsThread(key.ownerThreadId)),
+            () => MessageDeliveryError.make({ reason: "validation", operation: "message owner" }),
+          ),
+        ),
+      nextDeadline: (owner) => local(owner, store.nextDeadline(owner)),
+    });
+  }),
+);
+
+/** Message progress shares the native alarm slot without blocking source runtime work. */
+export const threadMessageDeliveryLayer = Layer.effectContext(
+  Effect.gen(function* () {
+    const driver = yield* MessageDeliveryDriver;
+    const store = yield* MessageDeliveryStore;
+
+    const failure = (operation: string) => () =>
+      DurableAlarmError.make({
+        operation,
+        message: "Durable message recovery remains pending",
+      });
+
+    const prepare = Effect.gen(function* () {
+      const deadline = yield* store.nextDeadline();
+
+      if (deadline === null || deadline > (yield* Clock.currentTimeMillis))
+        return { timeoutMillis: 1, run: Effect.succeed(Option.fromNullishOr(deadline)) };
+      // The assembled driver has four permits: a wave is one parallel attempt window.
+      const keys = yield* store.due(yield* Clock.currentTimeMillis, 4);
+      const records = yield* Effect.forEach(keys, (key) => store.get(key));
+
+      return {
+        timeoutMillis: Math.max(
+          1,
+          ...records.map((record) => record?.policy.attemptTimeoutMillis ?? 1),
+        ),
+        run: Effect.forEach(keys, (key) => driver.process(key), {
+          concurrency: 4,
+          discard: true,
+        }).pipe(
+          Effect.andThen(store.nextDeadline()),
+          Effect.map(Option.fromNullishOr),
+          Effect.mapError(failure("dispatch message delivery")),
+        ),
+      };
+    }).pipe(Effect.mapError(failure("prepare message delivery")));
+
+    return Context.make(ThreadMessageDelivery, {
+      prepare,
+    });
+  }),
+);

package/src/internal/prepared-admission.ts

@@ -0,0 +1,116 @@
+import { type DurableSubmitAgent } from "@yielded/agent/durable-agent-runtime";
+import { type AgentId } from "@yielded/agent/identifiers";
+import { PreparedInputAdmission } from "@yielded/agent/prepared-input-admission";
+import { PersistedJson } from "@yielded/agent/records";
+import {
+  type ScheduledEnvelope,
+  ScheduledInputAdmission,
+  ScheduledInputRetryable,
+  ScheduledInputRefused,
+  ScheduleStorageError,
+} from "@yielded/agent/schedule";
+import { type PreparedInput } from "@yielded/agent/subscription";
+import { Effect, Layer } from "effect";
+
+import { CloudflareThreadClient, type ThreadClientError } from "../CloudflareThreadClient.ts";
+
+const passthroughAgent = (agentId: AgentId): DurableSubmitAgent<typeof PersistedJson> => ({
+  definition: { id: agentId, input: PersistedJson },
+});
+
+/** Ordinary prepared admission through one freshly addressed Thread Object call. */
+export const cloudflarePreparedInputAdmissionLayer: Layer.Layer<
+  PreparedInputAdmission,
+  never,
+  CloudflareThreadClient
+> = Layer.effect(
+  PreparedInputAdmission,
+  Effect.gen(function* () {
+    const client = yield* CloudflareThreadClient;
+
+    return PreparedInputAdmission.of({
+      submissionStatus: (receipt) =>
+        client
+          .submissionStatus(receipt)
+          .pipe(Effect.mapError(() => ScheduledInputRetryable.make({ reason: "storage" }))),
+      submit: (envelope) =>
+        client
+          .submit(passthroughAgent(envelope.agentId), envelope.input, {
+            threadId: envelope.threadId,
+            principal: envelope.deliveryPrincipal,
+            idempotencyKey: envelope.admissionKey,
+            ...(envelope.admissionGroup === undefined
+              ? {}
+              : { admissionGroup: envelope.admissionGroup }),
+            ...(envelope.admissionFence === undefined
+              ? {}
+              : { admissionFence: envelope.admissionFence }),
+            ...(envelope.workerAdmission === undefined
+              ? {}
+              : { workerAdmission: envelope.workerAdmission }),
+            ...(envelope.messageAdmission === undefined
+              ? {}
+              : { messageAdmission: envelope.messageAdmission }),
+            definitions: envelope.definitions,
+          })
+          .pipe(
+            Effect.catchTags({
+              AdmissionConflict: () =>
+                ScheduleStorageError.make({ operation: "prepared admission", reason: "corrupt" }),
+              AdmissionLimitExceeded: () => ScheduledInputRetryable.make({ reason: "capacity" }),
+              ThreadClientError: (error: ThreadClientError) =>
+                ScheduledInputRetryable.make({
+                  reason: error.overloaded === true ? "capacity" : "transport",
+                }),
+              HostProtocolError: () => ScheduledInputRetryable.make({ reason: "ambiguous" }),
+              AdmissionPolicyError: (error) =>
+                error.reason === "refused"
+                  ? ScheduledInputRefused.make({ code: error.code })
+                  : ScheduledInputRetryable.make({
+                      reason: error.reason === "occupied" ? "capacity" : "storage",
+                    }),
+              LedgerError: () => ScheduledInputRetryable.make({ reason: "storage" }),
+              ThreadStoreError: () => ScheduledInputRetryable.make({ reason: "storage" }),
+              DurableAlarmError: () => ScheduledInputRetryable.make({ reason: "storage" }),
+              AgentInputError: () =>
+                ScheduleStorageError.make({ operation: "prepared admission", reason: "corrupt" }),
+              DigestError: () =>
+                ScheduleStorageError.make({ operation: "prepared admission", reason: "corrupt" }),
+              ThreadNotMaterialized: () => ScheduledInputRetryable.make({ reason: "storage" }),
+              AppendConflict: () => ScheduledInputRetryable.make({ reason: "ambiguous" }),
+              FenceRejected: () => ScheduledInputRetryable.make({ reason: "ambiguous" }),
+              DurableRuntimeFailpointError: () =>
+                ScheduledInputRetryable.make({ reason: "ambiguous" }),
+            }),
+          ),
+    });
+  }),
+);
+
+const preparedFromSchedule = (envelope: ScheduledEnvelope): PreparedInput => ({
+  schemaVersion: 1,
+  threadId: envelope.threadId,
+  deliveryPrincipal: envelope.deliveryPrincipal,
+  ...(envelope.admissionGroup === undefined ? {} : { admissionGroup: envelope.admissionGroup }),
+  ...(envelope.admissionFence === undefined ? {} : { admissionFence: envelope.admissionFence }),
+  agentId: envelope.agentId,
+  definitions: envelope.definitions,
+  input: envelope.input,
+  inputDigest: envelope.inputDigest,
+  admissionKey: envelope.admissionKey,
+  authorization: envelope.authorization,
+});
+
+/** Compatibility adapter retaining Scheduling's public admission port. */
+export const cloudflareScheduledInputAdmissionLayer: Layer.Layer<
+  ScheduledInputAdmission,
+  never,
+  PreparedInputAdmission
+> = Layer.effect(
+  ScheduledInputAdmission,
+  Effect.map(PreparedInputAdmission, (admission) =>
+    ScheduledInputAdmission.of({
+      submit: (envelope) => admission.submit(preparedFromSchedule(envelope)),
+    }),
+  ),
+);

package/src/internal/progress-wait.ts

@@ -0,0 +1,121 @@
+import { Context, Deferred, Effect, Layer, Ref, type Scope } from "effect";
+
+/** Cancellation tombstones are bounded hints, never durable authority. */
+const MAX_CANCELLATION_TOMBSTONES = 1_024;
+
+type ActiveRegistration = ReadonlySet<Deferred.Deferred<void>>;
+type Registration = ActiveRegistration | "cancelled";
+type Registrations = ReadonlyMap<string, Registration>;
+
+/**
+ * Per-incarnation cancellation registry for long-lived progress RPCs. The public runtime owns
+ * the actual wake registration; this host-only registry lets an interrupted Worker Effect ask
+ * the Object to interrupt its scoped wait before the Worker execution context itself ends.
+ */
+export class ProgressWaitRegistry extends Context.Service<
+  ProgressWaitRegistry,
+  {
+    /** Register a Scope-owned cancellation signal, observing any early cancel tombstone. */
+    readonly subscribe: (
+      waiterId: string,
+    ) => Effect.Effect<Effect.Effect<void>, never, Scope.Scope>;
+    /** Cancel every attempt and retain a bounded tombstone for later transport attempts. */
+    readonly cancel: (waiterId: string) => Effect.Effect<void>;
+  }
+>()("@effect-agent/platform-cloudflare/ProgressWaitRegistry") {
+  static readonly layer: Layer.Layer<ProgressWaitRegistry> = Layer.effect(
+    ProgressWaitRegistry,
+    Effect.gen(function* () {
+      const registrations = yield* Ref.make<Registrations>(new Map());
+
+      const remove = (waiterId: string, deferred: Deferred.Deferred<void>) =>
+        Ref.update(registrations, (current) => {
+          const existing = current.get(waiterId);
+
+          if (existing === undefined || existing === "cancelled" || !existing.has(deferred)) {
+            return current;
+          }
+          const next = new Map(current);
+          const active = new Set(existing);
+
+          active.delete(deferred);
+          if (active.size === 0) {
+            next.delete(waiterId);
+          } else {
+            next.set(waiterId, active);
+          }
+
+          return next;
+        });
+
+      const subscribe = Effect.fn("ProgressWaitRegistry.subscribe")(
+        (waiterId: string): Effect.Effect<Effect.Effect<void>, never, Scope.Scope> =>
+          Effect.gen(function* () {
+            const deferred = yield* Deferred.make<void>();
+
+            yield* Effect.addFinalizer(() => remove(waiterId, deferred));
+
+            const cancelled = yield* Ref.modify(registrations, (current) => {
+              const existing = current.get(waiterId);
+              const next = new Map(current);
+
+              if (existing === "cancelled") {
+                return [true, current] as const;
+              }
+              const active = new Set(existing ?? []);
+
+              active.add(deferred);
+              next.set(waiterId, active);
+
+              return [false, next] as const;
+            });
+
+            return { cancelled, deferred };
+          }).pipe(
+            Effect.map(({ cancelled, deferred }) =>
+              cancelled ? Effect.void : Deferred.await(deferred),
+            ),
+          ),
+      );
+
+      // Updating the registry and completing captured signals form one nonblocking operation;
+      // interruption between them must not strand attempts removed from the active registry.
+      const cancel = Effect.fn("ProgressWaitRegistry.cancel")(function* (waiterId: string) {
+        const waiters = yield* Ref.modify(
+          registrations,
+          (current): readonly [ReadonlyArray<Deferred.Deferred<void>>, Registrations] => {
+            const existing = current.get(waiterId);
+
+            if (existing === "cancelled") return [[], current] as const;
+            const next = new Map(current);
+
+            // A retry may arrive after an active attempt was cancelled. Retain the same
+            // tombstone used for early cancellation, ordered by cancellation time.
+            next.delete(waiterId);
+            next.set(waiterId, "cancelled");
+            let tombstones = 0;
+
+            for (const registration of next.values()) {
+              if (registration === "cancelled") tombstones += 1;
+            }
+            if (tombstones > MAX_CANCELLATION_TOMBSTONES) {
+              for (const [id, registration] of next) {
+                if (registration !== "cancelled") continue;
+                next.delete(id);
+                break;
+              }
+            }
+
+            return [existing === undefined ? [] : [...existing], next] as const;
+          },
+        );
+
+        yield* Effect.forEach(waiters, (waiter) => Deferred.succeed(waiter, undefined), {
+          discard: true,
+        });
+      }, Effect.uninterruptible);
+
+      return ProgressWaitRegistry.of({ subscribe, cancel });
+    }),
+  );
+}

package/src/internal/transport.ts

@@ -0,0 +1,56 @@
+import {
+  ThreadPortTransport,
+  portTransportFailure,
+} from "@yielded/agent-storage-cloudflare/port-routing";
+import type { ThreadId } from "@yielded/agent/identifiers";
+import { Effect, Layer } from "effect";
+import { RpcTracing } from "effect-cf";
+
+import { callThreadObject, ThreadObjectNamespace } from "../CloudflareBindings.ts";
+
+/**
+ * `ThreadPortTransport` over native Durable Object JS RPC (decision D-P6-3): one
+ * `portCall(envelope)` on the stub of the Object that owns the addressed Thread
+ * (`namespace.idFromName(threadId)` — the identity rule, plan §1.2). The envelopes are
+ * already Schema-encoded JSON, so the RPC boundary carries only structured-cloneable values;
+ * the protocol module stays transport-agnostic and fetch-with-JSON remains the documented
+ * fallback carrier.
+ * The namespace's optional `rpcTracing` setting uses the same transient trailing context
+ * as host calls; it never changes the encoded port envelope.
+ *
+ * Every delivery problem — stub construction, RPC rejection, overload, deploy-in-progress —
+ * surfaces as `PortTransportError` (preserving the platform stub's own `retryable` signal
+ * when present) and NEVER as a fabricated answer: on `resolveAdmission` the routing layer
+ * turns exactly this error into `AdmissionIndeterminate` (SUB-031).
+ */
+export const threadPortTransportLayer: Layer.Layer<
+  ThreadPortTransport,
+  never,
+  ThreadObjectNamespace
+> = Layer.effect(ThreadPortTransport)(
+  Effect.gen(function* () {
+    const namespace = yield* ThreadObjectNamespace;
+    const { rpcTracing } = namespace;
+
+    return ThreadPortTransport.of({
+      call: Effect.fn(
+        function* (threadId: ThreadId, request: unknown) {
+          const traceArgs =
+            rpcTracing === undefined ? [] : yield* RpcTracing.withRpcTraceContext([]);
+
+          return yield* callThreadObject(
+            threadId,
+            (target) => target.portCall(request, ...traceArgs),
+            (cause) => portTransportFailure(threadId, cause),
+          ).pipe(Effect.provideService(ThreadObjectNamespace, namespace));
+        },
+        (effect, threadId) =>
+          rpcTracing === undefined
+            ? Effect.withSpan(effect, "CloudflarePortTransport.call", {
+                attributes: { threadId },
+              })
+            : RpcTracing.withRpcClientSpan(effect, rpcTracing, "portCall"),
+      ),
+    });
+  }),
+);

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.