@effect-agent/storage-cloudflare 0.1.0-beta.11 → 0.1.0-beta.111

package/src/MemoryProtocol.ts

@@ -0,0 +1,351 @@
+import { Clock, Context, Effect, Schema } from "effect";
+import * as MemoryNamespace from "effect-agent/memory-namespace";
+import { MemoryLookup, MemoryRecallError, MemoryRecallLimits } from "effect-agent/memory-reference";
+import { MemoryAccess, revalidateMemoryLookup } from "effect-agent/memory-revalidation";
+import {
+  MemoryKey,
+  MemoryReader,
+  MemoryConflict,
+  MemoryDocument,
+  MemoryMutationFailure,
+  MemoryOperationConflict,
+  MemoryStorageError,
+  MemoryWithdrawn,
+  MemoryWrite,
+  MemoryWriter,
+} from "effect-agent/memory-store";
+import {
+  MemoryIndexSearch,
+  MemoryIndexError,
+  SemanticMemoryProfile,
+} from "effect-agent/semantic-memory-index";
+import {
+  SemanticMemoryError,
+  SemanticCandidateLimits,
+  SemanticCandidateResult,
+  revalidateSemanticMemoryCandidates,
+} from "effect-agent/semantic-memory-revalidation";
+import { Principal } from "effect-agent/submission-ledger";
+
+export class MemoryRpcError extends Schema.TaggedError<MemoryRpcError>()("MemoryRpcError", {
+  reason: Schema.Literals(["denied", "protocol", "budget", "timeout", "unavailable"]),
+}) {}
+
+export class MemoryRpcLimits extends Schema.Class<MemoryRpcLimits>(
+  "@effect-agent/storage-cloudflare/MemoryRpcLimits",
+)({
+  maxRequestBytes: Schema.Int.check(Schema.isBetween({ minimum: 256, maximum: 4_194_304 })),
+  maxResponseBytes: Schema.Int.check(Schema.isBetween({ minimum: 256, maximum: 16_777_216 })),
+  maxSourceBytes: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 67_108_864 })),
+  maxSources: MemoryRecallLimits.fields.maxSources,
+  timeoutMillis: MemoryRecallLimits.fields.timeoutMillis,
+}) {}
+
+export const defaultMemoryRpcLimits = MemoryRpcLimits.make({
+  maxRequestBytes: 1_048_576,
+  maxResponseBytes: 4_194_304,
+  maxSourceBytes: 16_777_216,
+  maxSources: 16,
+  timeoutMillis: 10_000,
+});
+
+const RequestFields = {
+  version: Schema.Literal(1),
+  access: MemoryAccess.Wire,
+  /** Host-authenticated identity, never copied from model input. The owner still authorizes it. */
+  principal: Principal,
+  deadlineMillis: Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0)),
+};
+
+const RevalidateRequest = Schema.TaggedStruct("Revalidate", {
+  ...RequestFields,
+  lookup: MemoryLookup,
+  limits: MemoryRecallLimits,
+});
+
+const ChangeRequest = Schema.TaggedStruct("Change", { ...RequestFields, write: MemoryWrite.Wire });
+
+const GetRequest = Schema.TaggedStruct("Get", { ...RequestFields, key: MemoryKey.Wire });
+
+const SemanticRequest: Schema.TaggedStruct<
+  "RevalidateSemantic",
+  typeof RequestFields & {
+    readonly found: typeof MemoryIndexSearch.Wire;
+    readonly profile: typeof SemanticMemoryProfile;
+    readonly limits: typeof SemanticCandidateLimits;
+  }
+> = Schema.TaggedStruct("RevalidateSemantic", {
+  ...RequestFields,
+  found: MemoryIndexSearch.Wire,
+  profile: SemanticMemoryProfile,
+  limits: SemanticCandidateLimits,
+});
+
+export const MemoryOwnerRequest: Schema.Union<
+  [typeof RevalidateRequest, typeof ChangeRequest, typeof SemanticRequest, typeof GetRequest]
+> = Schema.Union([RevalidateRequest, ChangeRequest, SemanticRequest, GetRequest]);
+
+export type MemoryOwnerRequest = typeof MemoryOwnerRequest.Type;
+
+export const MemoryOwnerFailure = Schema.Union([
+  MemoryRpcError,
+  MemoryStorageError,
+  MemoryRecallError,
+  MemoryConflict,
+  MemoryWithdrawn,
+  MemoryOperationConflict,
+  MemoryMutationFailure,
+  MemoryIndexError,
+  SemanticMemoryError,
+]);
+
+export type MemoryOwnerFailure = typeof MemoryOwnerFailure.Type;
+
+const LookupResponse = Schema.TaggedStruct("Lookup", {
+  access: MemoryAccess.Wire,
+  lookup: MemoryLookup,
+});
+
+const ChangedResponse = Schema.TaggedStruct("Changed", {
+  access: MemoryAccess.Wire,
+  document: MemoryDocument.Wire,
+});
+
+const SemanticResponse = Schema.TaggedStruct("Semantic", {
+  access: MemoryAccess.Wire,
+  result: SemanticCandidateResult,
+});
+
+const DocumentResponse = Schema.TaggedStruct("Document", {
+  access: MemoryAccess.Wire,
+  key: MemoryKey.Wire,
+  document: Schema.NullOr(MemoryDocument.Wire),
+});
+
+const FailedResponse = Schema.TaggedStruct("Failed", { failure: MemoryOwnerFailure });
+
+export const MemoryOwnerResponse: Schema.Union<
+  [
+    typeof LookupResponse,
+    typeof ChangedResponse,
+    typeof SemanticResponse,
+    typeof DocumentResponse,
+    typeof FailedResponse,
+  ]
+> = Schema.Union([
+  LookupResponse,
+  ChangedResponse,
+  SemanticResponse,
+  DocumentResponse,
+  FailedResponse,
+]);
+
+export type MemoryOwnerResponse = typeof MemoryOwnerResponse.Type;
+
+/**
+ * Fail-closed application policy. Authorize the namespace, principal, scope, and full command.
+ * Get requires exact-key authority, including application source/provenance checks where needed.
+ * Possession of a key or scope is not authorization, including for absent or withdrawn documents.
+ */
+export class MemoryOwnerAuthorizer extends Context.Service<
+  MemoryOwnerAuthorizer,
+  {
+    readonly authorize: (request: MemoryOwnerRequest) => Effect.Effect<void, MemoryRpcError>;
+  }
+>()("@effect-agent/storage-cloudflare/MemoryOwnerAuthorizer") {}
+
+/** Canonical namespace derived from this object's idFromName identity, never its request. */
+export class MemoryOwnerIdentity extends Context.Service<
+  MemoryOwnerIdentity,
+  {
+    readonly namespace: MemoryNamespace.Any;
+  }
+>()("@effect-agent/storage-cloudflare/MemoryOwnerIdentity") {}
+
+export const memoryWireBytes = (text: string): number => new TextEncoder().encode(text).byteLength;
+
+export const decodeMemoryWire = Effect.fn("decodeMemoryWire")(function* <A, I>(
+  schema: Schema.Codec<A, I, never>,
+  raw: unknown,
+  maxBytes: number,
+) {
+  const text = yield* Schema.decodeUnknownEffect(Schema.String)(raw).pipe(
+    Effect.mapError(() => MemoryRpcError.make({ reason: "protocol" })),
+  );
+
+  if (text.length > maxBytes || memoryWireBytes(text) > maxBytes)
+    return yield* MemoryRpcError.make({ reason: "budget" });
+
+  return yield* Schema.decodeEffect(Schema.fromJsonString(schema))(text).pipe(
+    Effect.mapError(() => MemoryRpcError.make({ reason: "protocol" })),
+  );
+});
+
+export const encodeMemoryWire = Effect.fn("encodeMemoryWire")(function* <A, I>(
+  schema: Schema.Codec<A, I, never, never>,
+  value: A,
+  maxBytes: number,
+) {
+  const encoded = yield* Schema.encodeEffect(Schema.fromJsonString(schema))(value).pipe(
+    Effect.mapError(() => MemoryRpcError.make({ reason: "protocol" })),
+  );
+
+  if (encoded.length > maxBytes || memoryWireBytes(encoded) > maxBytes)
+    return yield* MemoryRpcError.make({ reason: "budget" });
+
+  return encoded;
+});
+
+/** One local read for Get, or per distinct candidate source. No discovery or background work. */
+export const handleMemoryOwnerRequest = Effect.fn("MemoryOwner.handleRequest")(function* (
+  raw: unknown,
+  limits: MemoryRpcLimits = defaultMemoryRpcLimits,
+): Effect.fn.Return<
+  string,
+  never,
+  MemoryOwnerIdentity | MemoryOwnerAuthorizer | MemoryReader | MemoryWriter
+> {
+  const result = yield* Effect.gen(function* (): Effect.fn.Return<
+    MemoryOwnerResponse,
+    MemoryOwnerFailure,
+    MemoryOwnerIdentity | MemoryOwnerAuthorizer | MemoryReader | MemoryWriter
+  > {
+    limits = yield* Schema.decodeEffect(MemoryRpcLimits)(limits).pipe(
+      Effect.mapError(() => MemoryRpcError.make({ reason: "protocol" })),
+    );
+    const request = yield* decodeMemoryWire(MemoryOwnerRequest, raw, limits.maxRequestBytes);
+    const { namespace } = yield* MemoryOwnerIdentity;
+
+    if (
+      !MemoryNamespace.equals(namespace, request.access.namespace) ||
+      (request._tag === "Get" && !MemoryNamespace.equals(namespace, request.key.namespace)) ||
+      (request._tag === "Change" &&
+        !MemoryNamespace.equals(namespace, request.write.key.namespace)) ||
+      (request._tag === "RevalidateSemantic" &&
+        request.found.candidates.some(
+          (candidate) => !MemoryNamespace.equals(namespace, candidate.key.namespace),
+        ))
+    )
+      return yield* MemoryRpcError.make({ reason: "denied" });
+
+    const remaining = Math.min(
+      limits.timeoutMillis,
+      request.deadlineMillis - (yield* Clock.currentTimeMillis),
+    );
+
+    if (remaining <= 0) return yield* MemoryRpcError.make({ reason: "timeout" });
+
+    return yield* Effect.gen(function* (): Effect.fn.Return<
+      MemoryOwnerResponse,
+      MemoryOwnerFailure,
+      MemoryOwnerAuthorizer | MemoryReader | MemoryWriter
+    > {
+      const authorizer = yield* MemoryOwnerAuthorizer;
+
+      yield* authorizer.authorize(request);
+      if (request._tag === "Get") {
+        const reader = yield* MemoryReader;
+        const current = yield* reader.get(request.key);
+
+        const document =
+          current === null ? null : yield* MemoryDocument.restore(namespace, current);
+
+        if (document !== null) {
+          if (document.key.id !== request.key.id || document.source.id !== request.key.id)
+            return yield* MemoryStorageError.make({
+              operation: "validate memory read identity",
+              reason: "corrupt",
+            });
+          if (
+            document._tag === "ActiveMemoryDocument" &&
+            !document.scopes.includes(request.access.scope)
+          )
+            return yield* MemoryRpcError.make({ reason: "denied" });
+
+          yield* encodeMemoryWire(MemoryDocument.Wire, document, limits.maxSourceBytes);
+        }
+
+        return { _tag: "Document", access: request.access, key: request.key, document };
+      }
+      if (request._tag === "Change") {
+        const writer = yield* MemoryWriter;
+
+        return {
+          _tag: "Changed",
+          access: request.access,
+          document: yield* writer.change(request.write),
+        };
+      }
+      if (request._tag === "RevalidateSemantic") {
+        if (
+          new Set(request.found.candidates.map((candidate) => candidate.key.id)).size >
+          limits.maxSources
+        )
+          return yield* MemoryRpcError.make({ reason: "budget" });
+
+        const result = yield* revalidateSemanticMemoryCandidates(
+          request.found,
+          request.access,
+          request.profile,
+          {
+            ...request.limits,
+            maxSourceBytes: Math.min(
+              limits.maxSourceBytes,
+              request.limits.maxSourceBytes ?? 16_777_216,
+            ),
+            maxOutputBytes: Math.min(
+              limits.maxResponseBytes,
+              request.limits.maxOutputBytes ?? 16_777_216,
+            ),
+          },
+        );
+
+        return { _tag: "Semantic", access: request.access, result };
+      }
+
+      const count =
+        request.lookup._tag === "Found"
+          ? new Set(request.lookup.passages.map((passage) => passage.source.id)).size
+          : 0;
+
+      if (count > Math.min(limits.maxSources, request.limits.maxSources))
+        return yield* MemoryRpcError.make({ reason: "budget" });
+
+      const lookup = yield* revalidateMemoryLookup(request.lookup, request.access, {
+        maxSourceBytes: limits.maxSourceBytes,
+        maxInputBytes: Math.min(limits.maxSourceBytes, request.limits.maxInputBytes ?? 16_777_216),
+      });
+
+      return { _tag: "Lookup", access: request.access, lookup };
+    }).pipe(
+      Effect.scoped,
+      Effect.timeoutOrElse({
+        duration: remaining,
+        orElse: () => Effect.fail(MemoryRpcError.make({ reason: "timeout" })),
+      }),
+    );
+  }).pipe(
+    Effect.flatMap((response) =>
+      encodeMemoryWire(MemoryOwnerResponse, response, limits.maxResponseBytes),
+    ),
+    Effect.result,
+  );
+
+  if (result._tag === "Success") return result.success;
+
+  return yield* encodeMemoryWire(
+    MemoryOwnerResponse,
+    {
+      _tag: "Failed",
+      failure: result.failure,
+    },
+    limits.maxResponseBytes,
+  ).pipe(
+    Effect.catch(() =>
+      Schema.encodeEffect(Schema.fromJsonString(MemoryOwnerResponse))({
+        _tag: "Failed",
+        failure: MemoryRpcError.make({ reason: "budget" }),
+      }).pipe(Effect.orDie),
+    ),
+  );
+});

package/src/{port-protocol.ts → PortProtocol.ts}

@@ -1,25 +1,20 @@
+import { Schema } from "effect";
+import {
+  MessageDeliveryError,
+  MessageDeliveryPageRequest,
+  MessageDeliveryPage,
+} from "effect-agent/message-delivery";
+import { CanonicalRecordEnvelope } from "effect-agent/records";
 import {
   AbortCommand,
   AbortIntent,
   AdmissionConflict,
+  AdmissionPolicyError,
   AdmissionRequest,
   AdmissionResolution,
   AdmissionResult,
-  AppendConflict,
-  AppendResult,
-  CanonicalRecordEnvelope,
   ChildSettledNotification,
   ChildSettledOutcome,
-  ConversationExport,
-  ConversationExportRequest,
-  ConversationMaterialization,
-  ConversationNotMaterialized,
-  ConversationRead,
-  ConversationStoreError,
-  ConversationTail,
-  ConversationTailRequest,
-  FenceRejected,
-  FencedAppendRequest,
   JoinedToHost,
   LedgerError,
   MarkReadyRequest,
@@ -27,33 +22,47 @@ import {
   SubmissionLookup,
   SubmissionLookupByKey,
   SubmissionSnapshot,
-} from "@effect-agent/session";
-import { Schema } from "effect";
+} from "effect-agent/submission-ledger";
+import {
+  AppendConflict,
+  AppendResult,
+  ThreadExport,
+  ThreadPeerCountRequest,
+  ThreadExportRequest,
+  ThreadMaterialization,
+  ThreadNotMaterialized,
+  ThreadReadRequest,
+  ThreadStoreError,
+  ThreadTail,
+  ThreadTailRequest,
+  FenceRejected,
+  FencedAppendRequest,
+} from "effect-agent/thread-store";
 
 /**
  * The cross-Durable-Object port protocol (plan §1.3, D-P6-3): Schema request/response/error
- * envelopes for the CLOSED route-capable subset of the session ports. One Conversation's
- * Durable Object executes another Conversation's request against its OWN local facets; the
+ * envelopes for the CLOSED route-capable subset of the thread ports. One Thread's
+ * Durable Object executes another Thread's request against its OWN local facets; the
  * envelopes here are the only values that cross the Object boundary, and they are
  * transport-agnostic — native Durable Object JS RPC is the shipped carrier, fetch-with-JSON
  * the documented fallback, and both move the same Schema-encoded JSON.
  *
  * The closed subset is exactly the set of operations the durable coordinator performs against
- * a FOREIGN Conversation (parent/child establishment, status checks, abort propagation,
- * child-settlement notification, and the child-conversation store operations used by
+ * a FOREIGN Thread (parent/child establishment, status checks, abort propagation,
+ * child-settlement notification, and the child-thread store operations used by
  * establishment, `verifySettledChild`, and result projection):
  *
  * - ledger: `admit`, `markReady`, `lookup`, `resolveAdmission`, `requestAbort`,
  *   `recordChildSettled`;
  * - store: `materialize`, `append`, `read` (one page), `inspectTail`, `export`.
  *
- * Every other port operation is lane-local by construction and is NOT given an envelope:
- * honesty over accidental distribution — the routing layer fails such calls fast and typed
- * instead of quietly widening the distributed surface.
+ * Every other port operation is lane-local and has no envelope. A foreign disposable
+ * recovery-cache load returns a miss so the caller can replay canonical history. Other
+ * foreign operations fail fast and typed instead of widening the distributed surface.
  *
  * Failures cross the boundary as the `PortFailure` union and re-decode on the caller side to
  * the SAME tagged error types the local facet would have produced, so routed calls keep
- * error-tag fidelity. `cause` chains inside `LedgerError`/`ConversationStoreError` travel as
+ * error-tag fidelity. `cause` chains inside `LedgerError`/`ThreadStoreError` travel as
  * Schema defects and do not claim instance fidelity across Objects (plan §2.8).
  */
 
@@ -71,7 +80,7 @@ export const boundPortDiagnostic = (value: string): string =>
 /**
  * The envelope itself could not be honored: the receiving Object could not decode the
  * request, or a response could not be encoded/decoded. It never carries port semantics —
- * callers fold it into the operation's base error (`LedgerError`/`ConversationStoreError`),
+ * callers fold it into the operation's base error (`LedgerError`/`ThreadStoreError`),
  * except `resolveAdmission`, which folds it into `AdmissionIndeterminate` because a
  * non-answer is never proof of absence (SUB-031).
  */
@@ -128,43 +137,54 @@ export class LedgerRecordChildSettledCall extends Schema.TaggedClass<LedgerRecor
   request: ChildSettledNotification,
 }) {}
 
-/** Routed `ConversationStore.materialize` against the owning Object. */
+/** Routed `ThreadStore.materialize` against the owning Object. */
 export class StoreMaterializeCall extends Schema.TaggedClass<StoreMaterializeCall>(
   "@effect-agent/storage-cloudflare/StoreMaterializeCall",
 )("StoreMaterialize", {
-  request: ConversationMaterialization,
+  request: ThreadMaterialization,
 }) {}
 
-/** Routed `ConversationStore.append` against the owning Object. */
+/** Routed `ThreadStore.append` against the owning Object. */
 export class StoreAppendCall extends Schema.TaggedClass<StoreAppendCall>(
   "@effect-agent/storage-cloudflare/StoreAppendCall",
 )("StoreAppend", {
   request: FencedAppendRequest,
 }) {}
 
-/** Routed one-page `ConversationStore.read`; the page bound is the request's own `limit`. */
+/** Routed one-page `ThreadStore.read`; the page bound is the request's own `limit`. */
 export class StoreReadPageCall extends Schema.TaggedClass<StoreReadPageCall>(
   "@effect-agent/storage-cloudflare/StoreReadPageCall",
 )("StoreReadPage", {
-  request: ConversationRead,
+  request: ThreadReadRequest,
 }) {}
 
-/** Routed `ConversationStore.inspectTail` against the owning Object. */
+/** Routed `ThreadStore.inspectTail` against the owning Object. */
 export class StoreInspectTailCall extends Schema.TaggedClass<StoreInspectTailCall>(
   "@effect-agent/storage-cloudflare/StoreInspectTailCall",
 )("StoreInspectTail", {
-  request: ConversationTailRequest,
+  request: ThreadTailRequest,
 }) {}
 
-/** Routed `ConversationStore.export` against the owning Object. */
+/** Routed `ThreadStore.export` against the owning Object. */
 export class StoreExportCall extends Schema.TaggedClass<StoreExportCall>(
   "@effect-agent/storage-cloudflare/StoreExportCall",
 )("StoreExport", {
-  request: ConversationExportRequest,
+  request: ThreadExportRequest,
 }) {}
 
+export class StoreCountPeerMessagesCall extends Schema.TaggedClass<StoreCountPeerMessagesCall>()(
+  "StoreCountPeerMessages",
+  { request: ThreadPeerCountRequest },
+) {}
+
+export class MessageDeliveryListCall extends Schema.TaggedClass<MessageDeliveryListCall>()(
+  "MessageDeliveryList",
+  { request: MessageDeliveryPageRequest },
+) {}
+
 /** Every request that may cross a Durable Object boundary — the CLOSED route-capable subset. */
 export const PortRequest = Schema.Union([
+  MessageDeliveryListCall,
   LedgerAdmitCall,
   LedgerMarkReadyCall,
   LedgerLookupCall,
@@ -176,7 +196,9 @@ export const PortRequest = Schema.Union([
   StoreReadPageCall,
   StoreInspectTailCall,
   StoreExportCall,
+  StoreCountPeerMessagesCall,
 ]);
+
 export type PortRequest = typeof PortRequest.Type;
 
 /** The wire form of one port request (what a transport actually carries). */
@@ -241,17 +263,28 @@ export class StoreReadPageResult extends Schema.TaggedClass<StoreReadPageResult>
 export class StoreInspectTailResult extends Schema.TaggedClass<StoreInspectTailResult>(
   "@effect-agent/storage-cloudflare/StoreInspectTailResult",
 )("StoreInspectTailResult", {
-  tail: ConversationTail,
+  tail: ThreadTail,
 }) {}
 
 export class StoreExportResult extends Schema.TaggedClass<StoreExportResult>(
   "@effect-agent/storage-cloudflare/StoreExportResult",
 )("StoreExportResult", {
-  export: ConversationExport,
+  export: ThreadExport,
 }) {}
 
+export class StoreCountPeerMessagesResult extends Schema.TaggedClass<StoreCountPeerMessagesResult>()(
+  "StoreCountPeerMessagesResult",
+  { count: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 1000 })) },
+) {}
+
+export class MessageDeliveryListResult extends Schema.TaggedClass<MessageDeliveryListResult>()(
+  "MessageDeliveryListResult",
+  { page: MessageDeliveryPage },
+) {}
+
 /** Every successful routed result. Callers narrow by the tag their request implies. */
 export const PortResult = Schema.Union([
+  MessageDeliveryListResult,
   LedgerAdmitResult,
   LedgerMarkReadyResult,
   LedgerLookupResult,
@@ -263,7 +296,9 @@ export const PortResult = Schema.Union([
   StoreReadPageResult,
   StoreInspectTailResult,
   StoreExportResult,
+  StoreCountPeerMessagesResult,
 ]);
+
 export type PortResult = typeof PortResult.Type;
 
 // ---------------------------------------------------------------------------
@@ -273,19 +308,22 @@ export type PortResult = typeof PortResult.Type;
 /**
  * Every typed failure a route-capable operation can produce on its owning Object, plus the
  * protocol's own `PortProtocolError`. Members re-decode to the SAME tagged classes the
- * session ports declare, so a routed caller observes identical error tags and fields.
+ * thread ports declare, so a routed caller observes identical error tags and fields.
  */
 export const PortFailure = Schema.Union([
+  MessageDeliveryError,
   AdmissionConflict,
+  AdmissionPolicyError,
   SettlementConflict,
   JoinedToHost,
   LedgerError,
-  ConversationStoreError,
-  ConversationNotMaterialized,
+  ThreadStoreError,
+  ThreadNotMaterialized,
   AppendConflict,
   FenceRejected,
   PortProtocolError,
 ]);
+
 export type PortFailure = typeof PortFailure.Type;
 
 /** The routed operation succeeded on its owning Object. */