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

package/src/CloudflareConfig.ts

@@ -0,0 +1,138 @@
+import { DEFAULT_MAX_STORED_VALUE_BYTES } from "@yielded/agent-storage-cloudflare/do-storage-config";
+import { DeploymentId } from "@yielded/agent/records";
+import { DEFAULT_OWNERSHIP_LEASE_DURATION } from "@yielded/agent/submission-ledger";
+import { Context, Duration, Schema } from "effect";
+
+/**
+ * Schema-validated configuration for the Cloudflare durable runtime (deployment spec §4:
+ * decoded once during Layer construction, exposed as a typed service; DEPLOY-003). Every
+ * cadence is in milliseconds; every bound is finite and checked before any resource opens.
+ */
+
+const PositiveMillis = Schema.Int.check(Schema.isGreaterThan(0));
+
+/** Maximum supported auxiliary wave equals the native message policy's five-minute ceiling. */
+export const AuxiliaryDispatchMillis = PositiveMillis.check(Schema.isLessThanOrEqualTo(300_000));
+const NonNegativeMillis = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+
+/** The supplied Cloudflare durable runtime configuration failed validation (DEPLOY-003). */
+export class CloudflarePlatformConfigError extends Schema.TaggedError<CloudflarePlatformConfigError>()(
+  "CloudflarePlatformConfigError",
+  {
+    message: Schema.String,
+    cause: Schema.optionalKey(Schema.Defect()),
+  },
+) {}
+
+/**
+ * An admission was refused by a host resource limit BEFORE any ledger row existed
+ * (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
+ * Thread Object's submit entry point before `DurableAgentRuntime.submit` runs, and
+ * nothing was admitted or written.
+ */
+export class AdmissionLimitExceeded extends Schema.TaggedError<AdmissionLimitExceeded>()(
+  "AdmissionLimitExceeded",
+  {
+    limit: Schema.Literals(["queue-depth", "input-bytes", "database-bytes"]),
+    actual: Schema.Int,
+    maximum: Schema.Int,
+  },
+) {
+  override get message() {
+    return (
+      `Admission refused before any ledger row existed: ${this.limit} ${this.actual} exceeds ` +
+      `the configured maximum ${this.maximum}. Accepted work is unaffected; retry after the ` +
+      "lane drains or raise the limit (DEPLOY-007)."
+    );
+  }
+}
+
+/** The platform's hard per-Object database cap (10 GB, developers.cloudflare.com limits). */
+export const CLOUDFLARE_DATABASE_CAP_BYTES = 10_000_000_000;
+
+/** Default database-size admission ceiling: a 1 GB safety margin under the platform cap. */
+export const DEFAULT_MAX_DATABASE_BYTES = 9_000_000_000;
+
+/**
+ * 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 Thread lane before new admissions refuse. */
+  maxQueueDepthPerLane: Schema.Int.check(
+    Schema.isGreaterThan(0),
+    Schema.isLessThanOrEqualTo(100_000),
+  ),
+  /** Maximum encoded input bytes; never above the storage per-value bound. */
+  maxInputBytes: Schema.Int.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(2_000_000)),
+  /** Maximum `ctx.storage.sql.databaseSize` at admission; stays under the 10 GB platform cap. */
+  maxDatabaseBytes: Schema.Int.check(
+    Schema.isGreaterThan(0),
+    Schema.isLessThanOrEqualTo(CLOUDFLARE_DATABASE_CAP_BYTES),
+  ),
+}) {}
+
+/**
+ * Validated Cloudflare durable runtime configuration. The producer identity of one
+ * 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).
+ */
+export class CloudflareDurableRuntimeConfigValue extends Schema.Class<CloudflareDurableRuntimeConfigValue>(
+  "@effect-agent/platform-cloudflare/CloudflareDurableRuntimeConfigValue",
+)({
+  deploymentId: DeploymentId,
+  /** 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,
+  /** Base delay of exponential backoff when a pass fails or makes no progress. */
+  alarmBackoffBase: PositiveMillis,
+  /** Ceiling of exponential backoff after failed or no-progress maintenance passes. */
+  alarmBackoffCap: PositiveMillis,
+  /** `awaitSettlement` ledger re-check cadence when no wake arrives. */
+  settlementPollInterval: PositiveMillis,
+  /** Worker ownership-lease renewal cadence during an active Attempt. */
+  leaseRenewalInterval: PositiveMillis,
+  /** Active-Run abort-intent poll cadence. */
+  abortPollInterval: PositiveMillis,
+  /** Canonical observation poll cadence of the Durable Object store. */
+  observationPollInterval: NonNegativeMillis,
+  /** One disposable projection backfill wave; independent of required live applyCommitted. */
+  projectionDispatchTimeoutMillis: AuxiliaryDispatchMillis,
+  /** Per-value byte bound; must stay under the platform's 2 MB SQLite value limit. */
+  maxStoredValueBytes: Schema.Int.check(
+    Schema.isGreaterThan(0),
+    Schema.isLessThanOrEqualTo(2_000_000),
+  ),
+  /** Opt-in full payload/digest-chain audit while opening the store. */
+  verifyOnOpen: Schema.Boolean,
+  limits: CloudflareAdmissionLimitsValue,
+}) {}
+
+/** Explicit configuration authority for the assembled Cloudflare durable runtime. */
+export class CloudflareDurableRuntimeConfig extends Context.Service<
+  CloudflareDurableRuntimeConfig,
+  CloudflareDurableRuntimeConfigValue
+>()("@effect-agent/platform-cloudflare/CloudflareDurableRuntimeConfig") {}
+
+/** Documented production defaults applied by `ThreadObject.layer`. */
+export const CLOUDFLARE_RUNTIME_DEFAULTS = {
+  ownershipLeaseDuration: Duration.toMillis(DEFAULT_OWNERSHIP_LEASE_DURATION),
+  alarmBackoffBase: 100,
+  alarmBackoffCap: 5_000,
+  settlementPollInterval: 500,
+  leaseRenewalInterval: 10_000,
+  abortPollInterval: 500,
+  observationPollInterval: 25,
+  projectionDispatchTimeoutMillis: 30_000,
+  maxStoredValueBytes: DEFAULT_MAX_STORED_VALUE_BYTES,
+  verifyOnOpen: false,
+  maxQueueDepthPerLane: 256,
+  maxInputBytes: DEFAULT_MAX_STORED_VALUE_BYTES,
+  maxDatabaseBytes: DEFAULT_MAX_DATABASE_BYTES,
+} as const;

package/src/CloudflareMemory.ts

@@ -0,0 +1,420 @@
+import {
+  type DoMemoryStorageLimits,
+  defaultDoMemoryStorageLimits,
+  doMemoryStoreLayerWithFailpoints,
+} from "@yielded/agent-storage-cloudflare/do-memory-store";
+import {
+  type MemoryOwnerAuthorizer,
+  decodeMemoryWire,
+  defaultMemoryRpcLimits,
+  encodeMemoryWire,
+  handleMemoryOwnerRequest,
+  MemoryOwnerIdentity,
+  MemoryOwnerRequest,
+  MemoryOwnerResponse,
+  MemoryRpcError,
+  MemoryRpcLimits,
+  type MemoryOwnerFailure,
+} from "@yielded/agent-storage-cloudflare/memory-protocol";
+import * as Memory from "@yielded/agent/memory";
+import * as MemoryNamespace from "@yielded/agent/memory-namespace";
+import { MemoryNamespaceAddress } from "@yielded/agent/memory-namespace";
+import { type MemoryLookup, MemoryRecallLimits } from "@yielded/agent/memory-reference";
+import { MemoryAccess } from "@yielded/agent/memory-revalidation";
+import {
+  type MemoryReader,
+  type MemoryWrite,
+  MemoryKey,
+  MemoryDocument,
+  MemoryMutationFailpoint,
+  MemoryStorageError,
+  MemoryWriter,
+} from "@yielded/agent/memory-store";
+import {
+  type MemoryIndexSearch,
+  type SemanticMemoryProfile,
+} from "@yielded/agent/semantic-memory-index";
+import { type SemanticCandidateLimits } from "@yielded/agent/semantic-memory-revalidation";
+import { Principal } from "@yielded/agent/submission-ledger";
+import { Clock, Context, Effect, Layer, Schema } from "effect";
+import {
+  DurableObject as EffectCfDurableObject,
+  DurableObjectState,
+  RpcTargets,
+  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.decodeEffect(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.decodeEffect(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.decodeEffect(MemoryOwnerRequest)(request).pipe(
+      Effect.mapError(() => MemoryRpcError.make({ reason: "protocol" })),
+    );
+
+    const encoded = yield* encodeMemoryWire(MemoryOwnerRequest, decoded, validated.maxRequestBytes);
+
+    const unavailable = (cause: unknown) => {
+      const error = MemoryRpcError.make({ reason: "unavailable" });
+
+      error.cause = cause;
+
+      return error;
+    };
+
+    const address = memoryObjectName(bound.namespace);
+
+    const target = yield* RpcTargets.get(namespace, address, () =>
+      namespace.get(namespace.idFromName(address)),
+    ).pipe(Effect.mapError(unavailable));
+
+    const raw = yield* Effect.tryPromise({
+      try: () => target.memory(encoded),
+      catch: unavailable,
+    }).pipe(Effect.tapCause(() => RpcTargets.invalidate(target)));
+
+    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.decodeEffect(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.decodeEffect(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,
+};