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

package/src/{config.ts → CloudflareConfig.ts}

@@ -1,5 +1,6 @@
-import { DEFAULT_OWNERSHIP_LEASE_DURATION, DeploymentId } from "@effect-agent/session";
-import { DEFAULT_MAX_STORED_VALUE_BYTES } from "@effect-agent/storage-cloudflare";
+import { DEFAULT_MAX_STORED_VALUE_BYTES } from "@effect-agent/storage-cloudflare/DoStorageConfig";
+import { DeploymentId } from "@effect-agent/thread/Records";
+import { DEFAULT_OWNERSHIP_LEASE_DURATION } from "@effect-agent/thread/SubmissionLedger";
 import { Context, Duration, Schema } from "effect";
 
 /**
@@ -25,7 +26,7 @@ export class CloudflarePlatformConfigError extends Schema.TaggedError<Cloudflare
  * (deployment spec §8, DEPLOY-007: "Admission has explicit bounded quota and overload
  * behavior... a typed rejection"). This is the DC analogue of `NodeDurableHost`'s
  * `AdmissionClosed` host gate: the port surface stays untouched, the refusal happens in the
- * Conversation Object's submit entry point before `DurableAgentRuntime.submit` runs, and
+ * Thread Object's submit entry point before `DurableAgentRuntime.submit` runs, and
  * nothing was admitted or written.
  */
 export class AdmissionLimitExceeded extends Schema.TaggedError<AdmissionLimitExceeded>()(
@@ -52,13 +53,13 @@ export const CLOUDFLARE_DATABASE_CAP_BYTES = 10_000_000_000;
 export const DEFAULT_MAX_DATABASE_BYTES = 9_000_000_000;
 
 /**
- * Explicit bounded admission quotas checked by the Conversation Object BEFORE admission
+ * Explicit bounded admission quotas checked by the Thread Object BEFORE admission
  * (exit gate "resource limits are checked before admission").
  */
 export class CloudflareAdmissionLimitsValue extends Schema.Class<CloudflareAdmissionLimitsValue>(
   "@effect-agent/platform-cloudflare/CloudflareAdmissionLimitsValue",
 )({
-  /** Maximum nonterminal Submissions per Conversation lane before new admissions refuse. */
+  /** Maximum nonterminal Submissions per Thread lane before new admissions refuse. */
   maxQueueDepthPerLane: Schema.Int.check(
     Schema.isGreaterThan(0),
     Schema.isLessThanOrEqualTo(100_000),
@@ -74,7 +75,7 @@ export class CloudflareAdmissionLimitsValue extends Schema.Class<CloudflareAdmis
 
 /**
  * Validated Cloudflare durable runtime configuration. The producer identity of one
- * Conversation Object is `{producerPrefix}:{conversationId}` — stable across incarnations of
+ * Thread Object is `{producerPrefix}:{threadId}` — stable across incarnations of
  * the same deployment, distinct across deployments — and producer-epoch fencing (not the
  * producer name) remains the correctness authority (DUR-006).
  */
@@ -82,7 +83,7 @@ export class CloudflareDurableRuntimeConfigValue extends Schema.Class<Cloudflare
   "@effect-agent/platform-cloudflare/CloudflareDurableRuntimeConfigValue",
 )({
   deploymentId: DeploymentId,
-  /** Head of the minted producer identity `{producerPrefix}:{conversationId}`. */
+  /** Head of the minted producer identity `{producerPrefix}:{threadId}`. */
   producerPrefix: Schema.NonEmptyString.check(Schema.isMaxLength(256)),
   /** Submission ownership lease duration (D5); fences work across Object incarnations. */
   ownershipLeaseDuration: PositiveMillis,
@@ -119,7 +120,7 @@ export class CloudflareDurableRuntimeConfig extends Context.Service<
   CloudflareDurableRuntimeConfigValue
 >()("@effect-agent/platform-cloudflare/CloudflareDurableRuntimeConfig") {}
 
-/** Documented production defaults applied by `CloudflareDurableRuntime.layer`. */
+/** Documented production defaults applied by `ThreadObject.layer`. */
 export const CLOUDFLARE_RUNTIME_DEFAULTS = {
   ownershipLeaseDuration: Duration.toMillis(DEFAULT_OWNERSHIP_LEASE_DURATION),
   alarmBackoffBase: 100,

package/src/CloudflareMemory.ts

@@ -0,0 +1,406 @@
+import * as Memory from "@effect-agent/core/Memory";
+import * as MemoryNamespace from "@effect-agent/core/MemoryNamespace";
+import { MemoryNamespaceAddress } from "@effect-agent/core/MemoryNamespace";
+import { type MemoryLookup, MemoryRecallLimits } from "@effect-agent/core/MemoryReference";
+import { MemoryAccess } from "@effect-agent/core/MemoryRevalidation";
+import {
+  type MemoryReader,
+  type MemoryWrite,
+  MemoryKey,
+  MemoryDocument,
+  MemoryMutationFailpoint,
+  MemoryStorageError,
+  MemoryWriter,
+} from "@effect-agent/core/MemoryStore";
+import {
+  type MemoryIndexSearch,
+  type SemanticMemoryProfile,
+} from "@effect-agent/core/SemanticMemoryIndex";
+import { type SemanticCandidateLimits } from "@effect-agent/core/SemanticMemoryRevalidation";
+import {
+  type DoMemoryStorageLimits,
+  defaultDoMemoryStorageLimits,
+  doMemoryStoreLayerWithFailpoints,
+} from "@effect-agent/storage-cloudflare/DoMemoryStore";
+import {
+  type MemoryOwnerAuthorizer,
+  decodeMemoryWire,
+  defaultMemoryRpcLimits,
+  encodeMemoryWire,
+  handleMemoryOwnerRequest,
+  MemoryOwnerIdentity,
+  MemoryOwnerRequest,
+  MemoryOwnerResponse,
+  MemoryRpcError,
+  MemoryRpcLimits,
+  type MemoryOwnerFailure,
+} from "@effect-agent/storage-cloudflare/MemoryProtocol";
+import { Principal } from "@effect-agent/thread/SubmissionLedger";
+import { Clock, Context, Effect, Layer, Schema } from "effect";
+import {
+  DurableObject as EffectCfDurableObject,
+  DurableObjectState,
+  type WorkerEnvironment,
+} from "effect-cf";
+
+export interface MemoryObjectRpc extends Rpc.DurableObjectBranded {
+  memory(encoded: string): Promise<string>;
+}
+
+export class MemoryObjectNamespace extends Context.Service<
+  MemoryObjectNamespace,
+  {
+    readonly namespace: DurableObjectNamespace<MemoryObjectRpc>;
+  }
+>()("@effect-agent/platform-cloudflare/MemoryObjectNamespace") {}
+
+/** Namespace version and identity are already canonicalized by MemoryNamespace. */
+export const memoryObjectName = (namespace: MemoryNamespace.Any): string => namespace.address;
+
+/**
+ * Effect-native, host-bound memory client. Recall revalidates the entire admitted lookup
+ * in one RPC and renders it locally. No retries or per-source splitting occur here.
+ * Interrupted callers stop waiting; the owner has its own deadline. A timed-out write
+ * may have committed: reconcile by sending the identical operation ID and command.
+ */
+const makeMemoryClient = Effect.fn("CloudflareMemoryClient.make")(function* <
+  Namespace extends MemoryNamespace.Any,
+>(
+  access: MemoryAccess<Namespace>,
+  principal: Principal,
+  rpcLimits: MemoryRpcLimits = defaultMemoryRpcLimits,
+) {
+  const validated = yield* Schema.decodeUnknownEffect(MemoryRpcLimits)(rpcLimits).pipe(
+    Effect.mapError(() => MemoryRpcError.make({ reason: "protocol" })),
+  );
+
+  const bound = yield* Schema.decodeUnknownEffect(MemoryAccess.Wire)(access).pipe(
+    Effect.mapError(() => MemoryRpcError.make({ reason: "protocol" })),
+  );
+
+  principal = yield* Schema.decodeUnknownEffect(Principal)(principal).pipe(
+    Effect.mapError(() => MemoryRpcError.make({ reason: "protocol" })),
+  );
+  const { namespace } = yield* MemoryObjectNamespace;
+
+  const call = Effect.fn("CloudflareMemoryClient.call")(function* (request: MemoryOwnerRequest) {
+    const decoded = yield* Schema.decodeUnknownEffect(MemoryOwnerRequest)(request).pipe(
+      Effect.mapError(() => MemoryRpcError.make({ reason: "protocol" })),
+    );
+
+    const encoded = yield* encodeMemoryWire(MemoryOwnerRequest, decoded, validated.maxRequestBytes);
+
+    const raw = yield* Effect.tryPromise({
+      try: () =>
+        namespace.get(namespace.idFromName(memoryObjectName(bound.namespace))).memory(encoded),
+      catch: () => MemoryRpcError.make({ reason: "unavailable" }),
+    });
+
+    const response = yield* decodeMemoryWire(MemoryOwnerResponse, raw, validated.maxResponseBytes);
+
+    if (response._tag === "Failed") return yield* response.failure;
+    if (
+      !MemoryNamespace.equals(response.access.namespace, bound.namespace) ||
+      response.access.scope !== bound.scope
+    )
+      return yield* MemoryRpcError.make({ reason: "protocol" });
+
+    return response;
+  });
+
+  const withinDeadline = <A, E, R>(effect: Effect.Effect<A, E, R>, timeoutMillis: number) =>
+    effect.pipe(
+      Effect.timeoutOrElse({
+        duration: timeoutMillis,
+        orElse: () => Effect.fail(MemoryRpcError.make({ reason: "timeout" })),
+      }),
+    );
+
+  const revalidate = Effect.fn("CloudflareMemoryClient.revalidate")(function* (
+    lookup: MemoryLookup,
+    limits: MemoryRecallLimits,
+  ) {
+    limits = yield* Schema.decodeUnknownEffect(MemoryRecallLimits)(limits).pipe(
+      Effect.mapError(() => MemoryRpcError.make({ reason: "protocol" })),
+    );
+    const timeoutMillis = Math.min(validated.timeoutMillis, limits.timeoutMillis);
+
+    return yield* Effect.gen(function* () {
+      const response = yield* call({
+        _tag: "Revalidate",
+        version: 1,
+        access: bound,
+        principal,
+        lookup,
+        limits,
+        deadlineMillis: (yield* Clock.currentTimeMillis) + timeoutMillis,
+      });
+
+      if (response._tag !== "Lookup") return yield* MemoryRpcError.make({ reason: "protocol" });
+
+      return response.lookup;
+    }).pipe((effect) => withinDeadline(effect, timeoutMillis));
+  });
+
+  const change = Effect.fn("CloudflareMemoryClient.change")(function* (
+    write: MemoryWrite<Namespace>,
+  ) {
+    if (!MemoryNamespace.equals(write.key.namespace, bound.namespace))
+      return yield* MemoryRpcError.make({ reason: "denied" });
+
+    return yield* Effect.gen(function* () {
+      const response = yield* call({
+        _tag: "Change",
+        version: 1,
+        access: bound,
+        principal,
+        write,
+        deadlineMillis: (yield* Clock.currentTimeMillis) + validated.timeoutMillis,
+      });
+
+      if (response._tag !== "Changed" || response.document.key.id !== write.key.id)
+        return yield* MemoryRpcError.make({ reason: "protocol" });
+
+      return yield* MemoryDocument.restore(access.namespace, response.document);
+    }).pipe((effect) => withinDeadline(effect, validated.timeoutMillis));
+  });
+
+  /**
+   * Read one exact current document in one owner RPC. Null means absent; withdrawals return
+   * tombstones. Denial, unavailable storage and deadlines fail typed, never become absence.
+   * Reads begun after an acknowledged write observe it or a later revision. The owner checks
+   * exact-key authority and active document scopes; source-dependent provenance policy remains
+   * application-owned. No extraction, job draining, embedding, discovery or rendering occurs.
+   */
+  const get = Effect.fn("CloudflareMemoryClient.get")(function* (key: MemoryKey<Namespace>) {
+    const decodedKey = yield* Schema.decodeUnknownEffect(MemoryKey.Wire)(key).pipe(
+      Effect.mapError(() => MemoryRpcError.make({ reason: "protocol" })),
+    );
+
+    if (!MemoryNamespace.equals(decodedKey.namespace, bound.namespace))
+      return yield* MemoryRpcError.make({ reason: "denied" });
+
+    return yield* Effect.gen(function* () {
+      const response = yield* call({
+        _tag: "Get",
+        version: 1,
+        access: bound,
+        principal,
+        key: decodedKey,
+        deadlineMillis: (yield* Clock.currentTimeMillis) + validated.timeoutMillis,
+      });
+
+      if (
+        response._tag !== "Document" ||
+        !MemoryNamespace.equals(response.key.namespace, bound.namespace) ||
+        response.key.id !== decodedKey.id
+      )
+        return yield* MemoryRpcError.make({ reason: "protocol" });
+      if (response.document === null) return null;
+      if (
+        response.document.key.id !== decodedKey.id ||
+        response.document.source.id !== decodedKey.id ||
+        (response.document._tag === "ActiveMemoryDocument" &&
+          !response.document.scopes.includes(bound.scope))
+      )
+        return yield* MemoryRpcError.make({ reason: "protocol" });
+
+      yield* encodeMemoryWire(MemoryDocument.Wire, response.document, validated.maxSourceBytes);
+
+      return yield* MemoryDocument.restore(access.namespace, response.document);
+    }).pipe((effect) => withinDeadline(effect, validated.timeoutMillis));
+  });
+
+  const revalidateSemantic = Effect.fn("CloudflareMemoryClient.revalidateSemantic")(function* (
+    found: MemoryIndexSearch<Namespace>,
+    profile: SemanticMemoryProfile,
+    limits: SemanticCandidateLimits,
+  ) {
+    return yield* Effect.gen(function* () {
+      const response = yield* call({
+        _tag: "RevalidateSemantic",
+        version: 1,
+        access: bound,
+        principal,
+        found,
+        profile,
+        limits,
+        deadlineMillis: (yield* Clock.currentTimeMillis) + validated.timeoutMillis,
+      });
+
+      if (response._tag !== "Semantic") return yield* MemoryRpcError.make({ reason: "protocol" });
+
+      return response.result;
+    }).pipe((effect) => withinDeadline(effect, validated.timeoutMillis));
+  });
+
+  /**
+   * Revalidate in one owner RPC, then render whole passages within the caller's budget.
+   * The bound source is essential: unavailable/stale results and matches that cannot fit
+   * fail instead of silently producing empty context. No-match remains successful.
+   * The single outcome has sourceId "memory". No embedding or candidate search is performed.
+   * Use revalidate with Memory.recall for multiple readers sharing one output budget.
+   */
+  const recall = Effect.fn("CloudflareMemoryClient.recall")(function* (
+    lookup: MemoryLookup,
+    limits: MemoryRecallLimits,
+    estimateTokens?: (text: string) => number,
+  ) {
+    return yield* Memory.recall(
+      [{ id: "memory", essential: true, read: revalidate(lookup, limits) }],
+      limits,
+      estimateTokens,
+    );
+  });
+
+  return { get, recall, revalidate, revalidateSemantic, change };
+});
+
+export const CloudflareMemoryClient = {
+  /** Bind access and principal using the MemoryObjectNamespace supplied by the application. */
+  make: makeMemoryClient,
+  /** Use a resolved Worker or Durable Object binding without manual service provisioning. */
+  fromBinding: Effect.fn("CloudflareMemoryClient.fromBinding")(function* <
+    Namespace extends MemoryNamespace.Any,
+  >(
+    binding: DurableObjectNamespace<MemoryObjectRpc>,
+    options: {
+      readonly access: MemoryAccess<Namespace>;
+      readonly principal: Principal;
+      readonly rpcLimits?: MemoryRpcLimits;
+    },
+  ) {
+    return yield* makeMemoryClient(options.access, options.principal, options.rpcLimits).pipe(
+      Effect.provideService(MemoryObjectNamespace, { namespace: binding }),
+    );
+  }),
+};
+
+/**
+ * Optional activity-processor destination. Keeps domain write errors intact; transport,
+ * authorization and deadline failures become the existing MemoryStorageError contract.
+ * Receipts remain authoritative, including after caller interruption or lost replies.
+ */
+export const cloudflareMemoryWriterLayer = (
+  access: MemoryAccess,
+  principal: Principal,
+  limits: MemoryRpcLimits = defaultMemoryRpcLimits,
+) =>
+  Layer.effect(
+    MemoryWriter,
+    Effect.gen(function* () {
+      const client = yield* CloudflareMemoryClient.make(access, principal, limits);
+
+      return MemoryWriter.fromAdapter({
+        change: (write) =>
+          client.change(write).pipe(
+            Effect.catchTag("MemoryRpcError", (error) =>
+              Effect.fail(
+                MemoryStorageError.make({
+                  operation: `memory RPC ${error.reason}`,
+                  reason:
+                    error.reason === "unavailable" || error.reason === "timeout"
+                      ? "unavailable"
+                      : "invalid-input",
+                }),
+              ),
+            ),
+            Effect.catchTag(["MemoryRecallError", "MemoryIndexError", "SemanticMemoryError"], () =>
+              Effect.fail(
+                MemoryStorageError.make({ operation: "memory RPC response", reason: "corrupt" }),
+              ),
+            ),
+          ),
+      });
+    }),
+  );
+
+type OwnerServices = MemoryReader | MemoryWriter | MemoryOwnerAuthorizer | MemoryOwnerIdentity;
+
+export interface MemoryObjectInstance extends InstanceType<
+  EffectCfDurableObject.DurableObjectClass<Record<never, never>, OwnerServices>
+> {
+  memory(encoded: string): Promise<string>;
+}
+
+export interface MemoryObjectClass {
+  new (ctx: globalThis.DurableObjectState, env: Cloudflare.Env): MemoryObjectInstance;
+}
+
+/**
+ * Dedicated SQLite owner, independent of Thread lifetimes. The host binds authorization
+ * after restoring its namespace definition from MemoryOwnerIdentity. Do not retain
+ * cleanup-scoped resources in the host Layer; it lives for the DO incarnation.
+ */
+const makeMemoryObject = <E>(
+  host: Layer.Layer<
+    MemoryOwnerAuthorizer,
+    E,
+    MemoryOwnerIdentity | DurableObjectState.DurableObjectState | WorkerEnvironment
+  >,
+  options: {
+    readonly storageLimits?: DoMemoryStorageLimits;
+    readonly rpcLimits?: MemoryRpcLimits;
+    readonly failpoints?: Layer.Layer<
+      MemoryMutationFailpoint,
+      never,
+      DurableObjectState.DurableObjectState
+    >;
+  } = {},
+): MemoryObjectClass => {
+  const identity = Layer.effect(
+    MemoryOwnerIdentity,
+    Effect.gen(function* () {
+      const state = yield* DurableObjectState.DurableObjectState;
+
+      const address = yield* Schema.decodeUnknownEffect(MemoryNamespaceAddress)(
+        state.raw.id.name,
+      ).pipe(Effect.mapError(() => MemoryRpcError.make({ reason: "denied" })));
+
+      return { namespace: MemoryNamespace.Any.make({ address }) };
+    }),
+  );
+
+  const store = Layer.unwrap(
+    Effect.map(DurableObjectState.DurableObjectState, (state) =>
+      doMemoryStoreLayerWithFailpoints(
+        state.raw.storage,
+        options.storageLimits ?? defaultDoMemoryStorageLimits,
+      ),
+    ),
+  ).pipe(Layer.provide(options.failpoints ?? MemoryMutationFailpoint.layer));
+
+  const application = Layer.merge(store, host).pipe(Layer.provideMerge(identity));
+
+  const runtime: Layer.Layer<
+    OwnerServices,
+    E | MemoryOwnerFailure,
+    DurableObjectState.DurableObjectState | WorkerEnvironment
+  > = Layer.effectContext(
+    Effect.gen(function* () {
+      const state = yield* DurableObjectState.DurableObjectState;
+      const scope = yield* Effect.scope;
+
+      yield* Schema.decodeUnknownEffect(MemoryRpcLimits)(
+        options.rpcLimits ?? defaultMemoryRpcLimits,
+      ).pipe(Effect.mapError(() => MemoryRpcError.make({ reason: "protocol" })));
+
+      return yield* state.blockConcurrencyWhile(Layer.buildWithScope(application, scope));
+    }),
+  );
+
+  const rpc = { memory: (encoded: string) => handleMemoryOwnerRequest(encoded, options.rpcLimits) };
+
+  return EffectCfDurableObject.make<
+    OwnerServices,
+    E | MemoryOwnerFailure,
+    never,
+    never,
+    typeof rpc
+  >(runtime, { rpc });
+};
+
+export const MemoryObject = {
+  /** Build the SQLite Durable Object class with the application's owner authorization Layer. */
+  make: makeMemoryObject,
+};