@dxos/functions 0.8.4-main.74a063c4e0 → 0.8.4-main.765dc60934

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/functions",
-  "version": "0.8.4-main.74a063c4e0",
+  "version": "0.8.4-main.765dc60934",
   "description": "Functions API.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "info@dxos.org",
   "sideEffects": false,
   "type": "module",
@@ -17,11 +17,6 @@
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
       "default": "./dist/lib/neutral/index.mjs"
-    },
-    "./Trace": {
-      "source": "./src/Trace.ts",
-      "types": "./dist/types/src/Trace.d.ts",
-      "default": "./dist/lib/neutral/Trace.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -35,20 +30,20 @@
     "@effect/ai-anthropic": "0.23.0",
     "@effect/platform": "0.94.4",
     "effect": "3.20.0",
-    "@dxos/ai": "0.8.4-main.74a063c4e0",
-    "@dxos/context": "0.8.4-main.74a063c4e0",
-    "@dxos/effect": "0.8.4-main.74a063c4e0",
-    "@dxos/echo-db": "0.8.4-main.74a063c4e0",
-    "@dxos/invariant": "0.8.4-main.74a063c4e0",
-    "@dxos/errors": "0.8.4-main.74a063c4e0",
-    "@dxos/log": "0.8.4-main.74a063c4e0",
-    "@dxos/node-std": "0.8.4-main.74a063c4e0",
-    "@dxos/protocols": "0.8.4-main.74a063c4e0",
-    "@dxos/schema": "0.8.4-main.74a063c4e0",
-    "@dxos/operation": "0.8.4-main.74a063c4e0",
-    "@dxos/keys": "0.8.4-main.74a063c4e0",
-    "@dxos/echo": "0.8.4-main.74a063c4e0",
-    "@dxos/types": "0.8.4-main.74a063c4e0"
+    "@dxos/ai": "0.8.4-main.765dc60934",
+    "@dxos/compute": "0.8.4-main.765dc60934",
+    "@dxos/context": "0.8.4-main.765dc60934",
+    "@dxos/echo": "0.8.4-main.765dc60934",
+    "@dxos/effect": "0.8.4-main.765dc60934",
+    "@dxos/echo-db": "0.8.4-main.765dc60934",
+    "@dxos/invariant": "0.8.4-main.765dc60934",
+    "@dxos/keys": "0.8.4-main.765dc60934",
+    "@dxos/log": "0.8.4-main.765dc60934",
+    "@dxos/node-std": "0.8.4-main.765dc60934",
+    "@dxos/protocols": "0.8.4-main.765dc60934",
+    "@dxos/schema": "0.8.4-main.765dc60934",
+    "@dxos/errors": "0.8.4-main.765dc60934",
+    "@dxos/types": "0.8.4-main.765dc60934"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -2,13 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './errors';
-export * from './example';
-export * as Process from './process/Process';
-export * as ServiceResolver from './process/ServiceResolver';
-export * from './process/StorageService';
 export * from './sdk';
 export * from './services';
 export * from './types';
 export * from './protocol';
-export * as Trace from './Trace';

package/src/protocol/functions-ai-http-client.test.ts

@@ -0,0 +1,105 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as HttpClient from '@effect/platform/HttpClient';
+import * as HttpClientRequest from '@effect/platform/HttpClientRequest';
+import * as Cause from 'effect/Cause';
+import * as Chunk from 'effect/Chunk';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import { describe, test } from 'vitest';
+
+import { FunctionsAiMemoizationMissError, FunctionsAiUpstreamError } from '@dxos/compute';
+import { runAndForwardErrors } from '@dxos/effect';
+import { type EdgeFunctionEnv } from '@dxos/protocols';
+
+import { FunctionsAiHttpClient } from './functions-ai-http-client';
+
+const makeStubService = (response: Response): EdgeFunctionEnv.FunctionsAiService => ({
+  fetch: async () => response as any,
+});
+
+const runRequest = (service: EdgeFunctionEnv.FunctionsAiService) =>
+  HttpClient.HttpClient.pipe(
+    Effect.flatMap((client) =>
+      client.execute(HttpClientRequest.post('http://internal/provider/anthropic/v1/messages')),
+    ),
+    Effect.provide(FunctionsAiHttpClient.layer(service)),
+  );
+
+const extractDefect = (exit: Exit.Exit<unknown, unknown>): Error | null => {
+  if (Exit.isSuccess(exit)) {
+    return null;
+  }
+  return (Chunk.toReadonlyArray(Cause.defects(exit.cause))[0] as Error | undefined) ?? null;
+};
+
+describe('FunctionsAiHttpClient', () => {
+  test('emits FunctionsAiMemoizationMissError when upstream returns the memoization_miss envelope', async ({
+    expect,
+  }) => {
+    const service = makeStubService(
+      new Response(
+        JSON.stringify({
+          type: 'error',
+          error: {
+            type: 'memoization_miss',
+            message: 'No memoized Anthropic conversation found for POST /v1/messages (key=abc).',
+            cacheKey: 'abc',
+          },
+        }),
+        { status: 500, headers: { 'content-type': 'application/json' } },
+      ),
+    );
+
+    const exit = await Effect.runPromiseExit(runRequest(service));
+    const error = extractDefect(exit);
+    expect(error).toBeInstanceOf(FunctionsAiMemoizationMissError);
+    expect(error?.name).toBe('FunctionsAiMemoizationMissError');
+    expect((error as any)?.context?.cacheKey).toBe('abc');
+    expect((error as any)?.context?.status).toBe(500);
+  });
+
+  test('emits FunctionsAiUpstreamError for generic JSON error envelopes', async ({ expect }) => {
+    const service = makeStubService(
+      new Response(
+        JSON.stringify({
+          type: 'error',
+          error: { type: 'overloaded_error', message: 'Server overloaded.' },
+        }),
+        { status: 529, headers: { 'content-type': 'application/json' } },
+      ),
+    );
+
+    const exit = await Effect.runPromiseExit(runRequest(service));
+    const error = extractDefect(exit);
+    expect(error).toBeInstanceOf(FunctionsAiUpstreamError);
+    expect((error as any)?.context?.type).toBe('overloaded_error');
+    expect((error as any)?.context?.status).toBe(529);
+  });
+
+  test('passes non-error responses through unchanged', async ({ expect }) => {
+    const service = makeStubService(
+      new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      }),
+    );
+
+    const result = await runAndForwardErrors(runRequest(service));
+    expect(result.status).toBe(200);
+  });
+
+  test('passes non-JSON 5xx responses through to the @effect/ai layer unchanged', async ({ expect }) => {
+    const service = makeStubService(
+      new Response('Internal Server Error', {
+        status: 500,
+        headers: { 'content-type': 'text/plain' },
+      }),
+    );
+
+    const result = await runAndForwardErrors(runRequest(service));
+    expect(result.status).toBe(500);
+  });
+});

package/src/protocol/functions-ai-http-client.ts

@@ -11,13 +11,40 @@ import * as FiberRef from 'effect/FiberRef';
 import * as Layer from 'effect/Layer';
 import * as Stream from 'effect/Stream';
 
+import { FunctionsAiMemoizationMissError, FunctionsAiUpstreamError } from '@dxos/compute';
 import { log } from '@dxos/log';
 import { type EdgeFunctionEnv, ErrorCodec } from '@dxos/protocols';
+
 /**
  * Copy pasted from https://github.com/Effect-TS/effect/blob/main/packages/platform/src/internal/fetchHttpClient.ts
  */
 export const requestInitTagKey = '@effect/platform/FetchHttpClient/FetchOptions';
 
+/**
+ * Shape of the JSON error envelope emitted by the upstream AI gateway (and by the memoization
+ * layer that fronts it in test environments).
+ *
+ * @example
+ * ```json
+ * {
+ *   "type": "error",
+ *   "error": {
+ *     "type": "memoization_miss",
+ *     "message": "No memoized Anthropic conversation found for ...",
+ *     "cacheKey": "114dae3db8fe60..."
+ *   }
+ * }
+ * ```
+ */
+type UpstreamErrorEnvelope = {
+  type?: string;
+  error?: {
+    type?: string;
+    message?: string;
+    cacheKey?: string;
+  };
+};
+
 export class FunctionsAiHttpClient {
   static make = (service: EdgeFunctionEnv.FunctionsAiService) =>
     HttpClient.make((request, url, signal, fiber) => {
@@ -47,7 +74,18 @@ export class FunctionsAiHttpClient {
               cause,
             });
           },
-        }).pipe(Effect.map((response) => HttpClientResponse.fromWeb(request, response)));
+        }).pipe(
+          Effect.flatMap((response) =>
+            // Inspect the body before handing the response to `@effect/ai` so that structured
+            // upstream errors surface as typed defects (`FunctionsAiUpstreamError` and friends)
+            // rather than as the generic `HttpResponseError` from `@effect/ai/AiError`.
+            Effect.flatMap(
+              Effect.promise(() => parseUpstreamError(response)),
+              (typedError) =>
+                typedError ? Effect.die(typedError) : Effect.succeed(HttpClientResponse.fromWeb(request, response)),
+            ),
+          ),
+        );
 
       switch (request.body._tag) {
         case 'Raw':
@@ -65,3 +103,39 @@ export class FunctionsAiHttpClient {
   static layer = (service: EdgeFunctionEnv.FunctionsAiService) =>
     Layer.succeed(HttpClient.HttpClient, FunctionsAiHttpClient.make(service));
 }
+
+/**
+ * Returns a typed error if the response is a non-2xx JSON payload matching
+ * {@link UpstreamErrorEnvelope}; otherwise returns `undefined` and the response is forwarded
+ * unchanged.
+ */
+const parseUpstreamError = async (response: Response): Promise<Error | undefined> => {
+  if (response.ok) {
+    return undefined;
+  }
+  const contentType = response.headers.get('content-type') ?? '';
+  if (!contentType.toLowerCase().includes('application/json')) {
+    return undefined;
+  }
+  let body: UpstreamErrorEnvelope;
+  try {
+    body = (await response.clone().json()) as UpstreamErrorEnvelope;
+  } catch {
+    return undefined;
+  }
+  if (!body || body.type !== 'error' || typeof body.error !== 'object' || body.error === null) {
+    return undefined;
+  }
+  const inner = body.error;
+  const message = inner.message ?? `Upstream AI service responded with HTTP ${response.status}`;
+  if (inner.type === 'memoization_miss' && typeof inner.cacheKey === 'string') {
+    return new FunctionsAiMemoizationMissError({
+      message,
+      context: { cacheKey: inner.cacheKey, status: response.status },
+    });
+  }
+  return new FunctionsAiUpstreamError({
+    message,
+    context: { type: inner.type, status: response.status, ...(inner.cacheKey ? { cacheKey: inner.cacheKey } : {}) },
+  });
+};

package/src/protocol/protocol.test.ts

@@ -4,16 +4,16 @@
 
 import { describe, test } from 'vitest';
 
-import { FunctionError } from '../errors';
-import fibFunc from '../example/fib';
-import replyFunc from '../example/reply';
+import { InvalidOperationInputError } from '@dxos/compute';
+import { FibonacciHandler, ReplyHandler } from '@dxos/compute/testing';
+
 import { wrapFunctionHandler } from './protocol';
 
 describe('wrapFunctionHandler', () => {
   test('wraps reply function and executes handler', async ({ expect }) => {
-    const wrapped = wrapFunctionHandler(replyFunc);
+    const wrapped = wrapFunctionHandler(ReplyHandler);
 
-    expect(wrapped.meta.key).toBe('example.org/function/reply');
+    expect(wrapped.meta.key).toBe('org.example.function.reply');
     expect(wrapped.meta.name).toBe('Reply');
 
     const testData = { message: 'hello' };
@@ -28,9 +28,9 @@ describe('wrapFunctionHandler', () => {
   });
 
   test('wraps fibonacci function with valid input', async ({ expect }) => {
-    const wrapped = wrapFunctionHandler(fibFunc);
+    const wrapped = wrapFunctionHandler(FibonacciHandler);
 
-    expect(wrapped.meta.key).toBe('example.org/function/fib');
+    expect(wrapped.meta.key).toBe('org.example.function.fib');
     expect(wrapped.meta.name).toBe('Fibonacci');
 
     const result = await wrapped.handler({
@@ -43,8 +43,8 @@ describe('wrapFunctionHandler', () => {
     expect(result).toEqual({ result: '55' });
   });
 
-  test('throws FunctionError on invalid input schema for fibonacci', async ({ expect }) => {
-    const wrapped = wrapFunctionHandler(fibFunc);
+  test('throws InvalidOperationInputError on invalid input schema for fibonacci', async ({ expect }) => {
+    const wrapped = wrapFunctionHandler(FibonacciHandler);
 
     await expect(
       wrapped.handler({
@@ -53,6 +53,6 @@ describe('wrapFunctionHandler', () => {
           services: {},
         },
       }),
-    ).rejects.toThrow(FunctionError);
+    ).rejects.toThrow(InvalidOperationInputError);
   });
 });

package/src/protocol/protocol.ts

@@ -5,31 +5,58 @@
 import * as AnthropicClient from '@effect/ai-anthropic/AnthropicClient';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
-import { AiModelResolver, AiService } from '@dxos/ai';
+import { AiModelResolver, AiService, OpaqueToolkit } from '@dxos/ai';
 import { AnthropicResolver } from '@dxos/ai/resolvers';
+import {
+  FunctionError,
+  InvalidOperationInputError,
+  InvalidOperationOutputError,
+  Operation,
+  OperationRegistry,
+  Trace,
+} from '@dxos/compute';
 import { LifecycleState, Resource } from '@dxos/context';
 import { Database, Feed, JsonSchema, Ref, type Type } from '@dxos/echo';
-import { EchoClient, type EchoDatabaseImpl, type QueueFactory, createFeedServiceLayer } from '@dxos/echo-db';
+import { createFeedServiceLayer, EchoClient, type EchoDatabaseImpl, type QueueFactory } from '@dxos/echo-db';
 import { refFromEncodedReference } from '@dxos/echo/internal';
 import { runAndForwardErrors } from '@dxos/effect';
 import { assertState, failedInvariant, invariant } from '@dxos/invariant';
-import { PublicKey } from '@dxos/keys';
-import { Operation } from '@dxos/operation';
-import { type FunctionProtocol } from '@dxos/protocols';
+import { PublicKey, type SpaceId } from '@dxos/keys';
+import { log } from '@dxos/log';
+import { EdgeFunctionEnv, ErrorCodec, type FunctionProtocol, type TraceProtocol } from '@dxos/protocols';
 
-import { FunctionError } from '../errors';
 import { type FunctionServices } from '../sdk';
-import { CredentialsService, FunctionInvocationService, QueueService, TracingService } from '../services';
-import * as Trace from '../Trace';
+import {
+  configuredCredentialsLayer,
+  credentialsLayerFromDatabase,
+  FunctionInvocationService,
+  QueueService,
+} from '../services';
 import { FunctionsAiHttpClient } from './functions-ai-http-client';
 
+export interface FunctionWrappingOptions {
+  /**
+   * Additional types to register with the database.
+   */
+  types?: Type.AnyEntity[];
+
+  /**
+   * Toolkits to make available via the `OpaqueToolkitProvider`.
+   */
+  toolkits?: OpaqueToolkit.OpaqueToolkit[];
+}
+
 /**
  * Wraps a function handler made with `defineFunction` to a protocol that the functions-runtime expects.
  */
-export const wrapFunctionHandler = (func: Operation.WithHandler<Operation.Definition.Any>): FunctionProtocol.Func => {
+export const wrapFunctionHandler = (
+  func: Operation.WithHandler<Operation.Definition.Any>,
+  opts: FunctionWrappingOptions = {},
+): FunctionProtocol.Func => {
   if (!Operation.isOperationWithHandler(func)) {
     throw new TypeError('Expected operation with handler');
   }
@@ -61,17 +88,21 @@ export const wrapFunctionHandler = (func: Operation.WithHandler<Operation.Defini
       try {
         if (!SchemaAST.isAnyKeyword(func.input.ast)) {
           try {
-            Schema.validateSync(func.input)(data);
-          } catch (error) {
-            throw new FunctionError({ message: 'Invalid input schema', cause: error });
+            Schema.validateSync(func.input, { onExcessProperty: 'error' })(data);
+          } catch (error: any) {
+            throw new InvalidOperationInputError({
+              message: `Operation input did not match schema (${func.meta.key}): ${error.message}`,
+              cause: error,
+            });
           }
         }
 
-        await using funcContext = await new FunctionContext(context).open();
+        await using funcContext = await new FunctionContext(context, opts).open();
 
-        if (func.types.length > 0) {
+        const types = [...(opts.types ?? []), ...(func.types ?? [])];
+        if (types.length > 0) {
           invariant(funcContext.db, 'Database is required for functions with types');
-          await funcContext.db.graph.schemaRegistry.register(func.types as Type.AnyEntity[]);
+          await funcContext.db.graph.schemaRegistry.register(types as Type.AnyEntity[]);
         }
 
         const dataWithDecodedRefs =
@@ -90,8 +121,27 @@ export const wrapFunctionHandler = (func: Operation.WithHandler<Operation.Defini
           );
         }
 
+        // Flush in-memory ECHO writes before the function scope closes.
+        // Writes performed by `db.add` / `db.remove` are buffered in the in-memory
+        // `EchoDatabaseImpl` and only pushed across the `DataService` binding when
+        // `db.flush({ disk })` is called. `FunctionContext._close` (invoked by the
+        // `await using` above) calls `db.close()` but does NOT flush, so mutations
+        // performed by handlers that declare `Database.Service` (e.g. `object-create`,
+        // `object-update`, `relation-create`) would be silently dropped before reaching
+        // the edge `AutomergeReplicator`. Flushing here closes that hole.
+        if (serviceTags.includes(Database.Service.key) && funcContext.db) {
+          await funcContext.db.flush({ disk: true, indexes: false });
+        }
+
         if (func.output && !SchemaAST.isAnyKeyword(func.output.ast)) {
-          Schema.validateSync(func.output)(result);
+          try {
+            Schema.validateSync(func.output, { onExcessProperty: 'error' })(result);
+          } catch (error: any) {
+            throw new InvalidOperationOutputError({
+              message: `Operation output did not match schema (${func.meta.key}): ${error.message}`,
+              cause: error,
+            });
+          }
         }
 
         return result;
@@ -111,10 +161,12 @@ class FunctionContext extends Resource {
   readonly client: EchoClient | undefined;
   db: EchoDatabaseImpl | undefined;
   queues: QueueFactory | undefined;
+  readonly opts: FunctionWrappingOptions;
 
-  constructor(context: FunctionProtocol.Context) {
+  constructor(context: FunctionProtocol.Context, opts: FunctionWrappingOptions) {
     super();
     this.context = context;
+    this.opts = opts;
     if (context.services.dataService && context.services.queryService) {
       this.client = new EchoClient().connectToService({
         dataService: context.services.dataService,
@@ -154,43 +206,164 @@ class FunctionContext extends Resource {
     const queuesLayer = this.queues ? QueueService.layer(this.queues) : QueueService.notAvailable;
     const feedLayer = this.queues ? createFeedServiceLayer(this.queues) : Feed.notAvailable;
     const credentials = dbLayer
-      ? CredentialsService.layerFromDatabase({ caching: true }).pipe(Layer.provide(dbLayer))
-      : CredentialsService.configuredLayer([]);
-    const functionInvocationService = MockedFunctionInvocationService;
-    const tracing = TracingService.layerNoop;
+      ? credentialsLayerFromDatabase({ caching: true }).pipe(Layer.provide(dbLayer))
+      : configuredCredentialsLayer([]);
 
     const aiLayer = this.context.services.functionsAiService
-      ? AiModelResolver.AiModelResolver.buildAiService.pipe(
-          Layer.provide(
-            AnthropicResolver.make().pipe(
-              Layer.provide(
-                AnthropicClient.layer({
-                  // Note: It doesn't matter what is base url here, it will be proxied to ai gateway in edge.
-                  apiUrl: 'http://internal/provider/anthropic',
-                }).pipe(Layer.provide(FunctionsAiHttpClient.layer(this.context.services.functionsAiService))),
-              ),
-            ),
-          ),
-        )
+      ? InternalAiServiceLayer(this.context.services.functionsAiService)
       : AiService.notAvailable;
 
+    const operationServiceLayer = this.context.services.functionsService
+      ? makeOperationServiceLayer(this.context.services.functionsService)
+      : unavailableOperationServiceLayer;
+
+    const operationRegistryLayer = this.context.services.functionsService
+      ? makeOperationRegistryLayer(this.context.services.functionsService, this.context.spaceId as SpaceId | undefined)
+      : emptyOperationRegistryLayer;
+
+    const traceWriterLayer = this.context.services.traceService
+      ? makeTraceWriterLayer(this.context.services.traceService)
+      : Trace.writerLayerNoop;
+
+    log('Creating function context layer', {
+      traceService: !!this.context.services.traceService,
+      functionsService: !!this.context.services.functionsService,
+      functionsAiService: !!this.context.services.functionsAiService,
+      spaceId: this.context.spaceId,
+      spaceRootUrl: this.context.spaceRootUrl,
+      toolkits: this.opts.toolkits?.length ?? 0,
+      types: this.opts.types?.length ?? 0,
+    });
+
     return Layer.mergeAll(
       dbLayer,
       queuesLayer,
       feedLayer,
       credentials,
-      functionInvocationService,
+      operationServiceLayer,
+      operationRegistryLayer,
       aiLayer,
-      tracing,
-      // TODO(dmaretskyi): Forward trace events.
-      Trace.writerLayerNoop,
+      OpaqueToolkit.providerLayer(OpaqueToolkit.merge(...(this.opts.toolkits ?? []))),
+      traceWriterLayer,
+
+      // `FunctionInvocationService` is deprecated; new code should yield `Operation.Service`.
+      // The cloudflare wrapper provides only the unavailable layer to satisfy the (still-present)
+      // type union — handlers that yield it will die at invocation time.
+      FunctionInvocationService.layerNotAvailable,
     );
   }
 }
 
-const MockedFunctionInvocationService = Layer.succeed(FunctionInvocationService, {
-  invokeFunction: () => Effect.die('Calling functions from functions is not implemented yet.'),
-  resolveFunction: () => Effect.die('Not implemented.'),
+/**
+ * Backs `Trace.TraceService` with the EDGE-provided `TraceService` so that operation
+ * handlers can write trace events that are forwarded to the runtime's trace sink.
+ */
+const makeTraceWriterLayer = (traceService: TraceProtocol.TraceService): Layer.Layer<Trace.TraceService> =>
+  Layer.succeed(Trace.TraceService, {
+    write: (eventType, payload) => {
+      log('Writing trace event', {
+        eventType: eventType.key,
+      });
+      traceService.write([
+        {
+          key: eventType.key,
+          isEphemeral: eventType.isEphemeral,
+          data: payload,
+        },
+      ]);
+    },
+  });
+
+/**
+ * AI service layer that proxies HTTP requests through the EDGE-provided `FunctionsAiService`.
+ */
+const InternalAiServiceLayer = (functionsAiService: EdgeFunctionEnv.FunctionsAiService) =>
+  AiModelResolver.AiModelResolver.buildAiService.pipe(
+    Layer.provide(
+      AnthropicResolver.make().pipe(
+        Layer.provide(
+          AnthropicClient.layer({
+            // Note: It doesn't matter what is base url here, it will be proxied to ai gateway in edge.
+            apiUrl: 'http://internal/provider/anthropic',
+          }).pipe(Layer.provide(FunctionsAiHttpClient.layer(functionsAiService))),
+        ),
+      ),
+    ),
+  );
+
+/**
+ * Backs `Operation.Service` with the EDGE-provided `FunctionsService` so that operation
+ * handlers can invoke other deployed operations remotely. The `deployedId` on the operation
+ * definition is used as the routing key.
+ */
+const makeOperationServiceLayer = (
+  functionsService: EdgeFunctionEnv.FunctionsService,
+): Layer.Layer<Operation.Service> => {
+  const invokeRemote = async (
+    op: Operation.Definition.Any,
+    input: unknown,
+    options?: Operation.InvokeOptions,
+  ): Promise<{ data?: unknown; error?: Error }> => {
+    invariant(op.meta.deployedId, `Operation '${op.meta.key}' has no deployedId; cannot invoke remotely.`);
+    const result = await functionsService.invoke(op.meta.deployedId, input, {
+      spaceId: options?.spaceId,
+    });
+    if (result._kind === 'success') {
+      return { data: result.data };
+    }
+    return { error: ErrorCodec.decode(result.error) };
+  };
+
+  return Layer.succeed(Operation.Service, {
+    invoke: ((op: Operation.Definition.Any, input: unknown, options?: Operation.InvokeOptions) =>
+      Effect.tryPromise(() => invokeRemote(op, input, options)).pipe(
+        Effect.orDie,
+        Effect.flatMap((outcome) =>
+          outcome.error ? Effect.die(outcome.error) : Effect.succeed(outcome.data as never),
+        ),
+      )) as Operation.OperationService['invoke'],
+    schedule: ((op: Operation.Definition.Any, input: unknown) =>
+      Effect.sync(() => {
+        invariant(op.meta.deployedId, `Operation '${op.meta.key}' has no deployedId; cannot schedule remotely.`);
+        // Fire and forget — schedule is intentionally non-awaiting.
+        void functionsService.invoke(op.meta.deployedId, input).catch(() => {
+          // Swallow errors — schedule is observability-only.
+        });
+      })) as Operation.OperationService['schedule'],
+    invokePromise: ((op: Operation.Definition.Any, input: unknown, options?: Operation.InvokeOptions) =>
+      invokeRemote(op, input, options).catch((error: unknown) => ({
+        error: error instanceof Error ? error : new Error(String(error)),
+      }))) as Operation.OperationService['invokePromise'],
+  } satisfies Operation.OperationService);
+};
+
+const unavailableOperationServiceLayer = Layer.succeed(Operation.Service, {
+  invoke: () => Effect.die('Operation.Service is not available: missing functionsService in EDGE context.'),
+  schedule: () => Effect.die('Operation.Service is not available: missing functionsService in EDGE context.'),
+  invokePromise: async () => ({
+    error: new Error('Operation.Service is not available: missing functionsService in EDGE context.'),
+  }),
+} as Operation.OperationService);
+
+/**
+ * Backs `OperationRegistry.Service` with the EDGE-provided `FunctionsService.query`. Returns
+ * the first persistent operation matching the requested key, or `Option.none()` when not found.
+ */
+const makeOperationRegistryLayer = (
+  functionsService: EdgeFunctionEnv.FunctionsService,
+  spaceId: SpaceId | undefined,
+): Layer.Layer<OperationRegistry.Service> =>
+  Layer.succeed(OperationRegistry.Service, {
+    resolve: (key: string) =>
+      Effect.gen(function* () {
+        const records = yield* Effect.tryPromise(() => functionsService.query({ spaceId })).pipe(Effect.orDie);
+        const match = (records as Operation.PersistentOperation[]).find((record) => Operation.getKey(record) === key);
+        return match ? Option.some(Operation.deserialize(match)) : Option.none();
+      }),
+  });
+
+const emptyOperationRegistryLayer = Layer.succeed(OperationRegistry.Service, {
+  resolve: () => Effect.succeed(Option.none()),
 });
 
 const decodeRefsFromSchema = (ast: SchemaAST.AST, value: unknown, db: EchoDatabaseImpl): unknown => {