@dxos/compute 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

package/src/Operation.ts

@@ -0,0 +1,513 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Pipeable from 'effect/Pipeable';
+import * as Schema$ from 'effect/Schema';
+import type * as Types from 'effect/Types';
+
+import { Annotation, JsonSchema, Obj, Ref, Type, type DXN, type Key } from '@dxos/echo';
+
+import type { NoHandlerError } from './errors';
+import type { Operation } from './index';
+
+// @import-as-namespace
+
+/**
+ * Schema type that accepts any Encoded form but requires no Context.
+ * This allows ECHO object schemas where Type !== Encoded due to [KindId] symbol.
+ */
+type Schema<T> = Schema$.Schema<T, any, never>;
+
+export const DefinitionTypeId = '~@dxos/operation/OperationDefinition' as const;
+export type DefinitionTypeId = typeof DefinitionTypeId;
+
+/**
+ * Serializable definition of an Operation.
+ * Contains schema and metadata, but no runtime logic.
+ */
+export interface Definition<I, O, S = any> extends Pipeable.Pipeable, Definition.Variance<I, O, S> {
+  /**
+   * Input schema for the operation.
+   */
+  readonly input: Schema<I>;
+  /**
+   * Output schema for the operation.
+   */
+  readonly output: Schema<O>;
+
+  readonly meta: {
+    readonly key: string;
+    readonly name?: string;
+    readonly version?: string;
+    readonly description?: string;
+    /**
+     * Deployment ID for remote invocation.
+     * Assigned by the EDGE function service when deployed.
+     */
+    readonly deployedId?: string;
+  };
+
+  /**
+   * Execution mode for the operation.
+   * - 'sync': Operation completes synchronously (fast, UI-blocking acceptable).
+   * - 'async': Operation may take time (should not block UI).
+   */
+  readonly executionMode: 'sync' | 'async';
+
+  /**
+   * ECHO types the operation uses.
+   * Ensures types are available when the operation is executed remotely.
+   */
+  readonly types: readonly Type.AnyEntity[];
+
+  /**
+   * Effect services required by this operation.
+   * These services will be automatically provided to the handler at invocation time.
+   */
+  readonly services: readonly Context.Tag<any, any>[];
+}
+
+/**
+ * Namespace for OperationDefinition helper types.
+ */
+export declare namespace Definition {
+  export interface Variance<I, O, S> {
+    [DefinitionTypeId]: {
+      readonly _Input: Types.Contravariant<I>;
+      readonly _Output: Types.Covariant<O>;
+      readonly _Services: Types.Covariant<S>;
+    };
+  }
+
+  /**
+   * Any operation definition, regardless of input/output types.
+   */
+  export type Any = Definition<any, any, any>;
+
+  /**
+   * Extract the input type from an operation definition.
+   */
+  export type Input<T extends Any> = T extends Variance<infer I, infer _O, infer _S> ? I : never;
+
+  /**
+   * Extract the output type from an operation definition.
+   */
+  export type Output<T extends Any> = T extends Variance<infer _I, infer O, infer _S> ? O : never;
+
+  /**
+   * Extract the service identifier types from an operation's services array.
+   * Returns `never` if the operation has no services declared.
+   */
+  export type Services<T extends Any> = T extends Variance<infer _I, infer _O, infer S> ? S : never;
+
+  export type HandlerType<T extends Any> =
+    T extends Variance<infer I, infer O, infer S> ? Handler<I, O, any, S> : never;
+}
+
+/**
+ * Runtime handler for an Operation.
+ */
+export type Handler<I, O, E = Error, R = never> = (input: I) => Effect.Effect<O, E, R>;
+
+export type WithHandler<T extends Definition.Any> = T & {
+  handler: Definition.HandlerType<T>;
+};
+
+/**
+ * Checks if a value is an operation definition.
+ */
+export const isOperationDefinition = (value: unknown): value is Definition.Any => {
+  return typeof value === 'object' && value !== null && DefinitionTypeId in value;
+};
+
+/**
+ * Checks if a value is an operation with a handler.
+ */
+export const isOperationWithHandler = (value: unknown): value is WithHandler<Definition.Any> => {
+  return isOperationDefinition(value) && 'handler' in value;
+};
+
+/**a
+ * Props for creating an Operation definition.
+ * Derived from OperationDefinition with executionMode made optional (defaults to 'async').
+ */
+export type Props<I, O> = Omit<Definition<I, O>, DefinitionTypeId | 'pipe' | 'executionMode' | 'types' | 'services'> & {
+  readonly executionMode?: 'sync' | 'async';
+  readonly types?: Definition<I, O>['types'];
+  readonly services?: Definition<I, O>['services'];
+};
+
+/**
+ * Creates a new Operation definition.
+ * Applies default executionMode of 'async' if not specified.
+ * The returned type preserves the literal types of props (including services).
+ */
+export const make = <const P extends Types.NoExcessProperties<Props<any, any>, P>>(
+  props: P,
+): Definition<
+  Schema$.Schema.Type<P['input']>,
+  Schema$.Schema.Type<P['output']>,
+  Context.Tag.Identifier<NonNullable<P['services']>[number]>
+> => {
+  return {
+    [DefinitionTypeId]: {},
+    ...props,
+    executionMode: props.executionMode ?? 'async',
+    types: props.types ?? [],
+    services: props.services ?? [],
+    pipe() {
+      // eslint-disable-next-line prefer-rest-params
+      return Pipeable.pipeArguments(this, arguments);
+    },
+  } as any;
+};
+
+/**
+ * Attaches a handler to an Operation definition.
+ * The handler may use any services declared in the operation, plus Operation.Service (always available).
+ * Dual API: can be called directly or used in a pipe.
+ *
+ * @example
+ * ```ts
+ * const MyOp = Operation.make({
+ *   input: Schema.Void,
+ *   output: Schema.Void,
+ *   meta: { key: 'my-op' },
+ *   services: [DatabaseService],
+ * });
+ *
+ * // Direct call - handler can use DatabaseService
+ * const op = Operation.withHandler(MyOp, (input) =>
+ *   Effect.gen(function* () {
+ *     const db = yield* DatabaseService;
+ *     return {};
+ *   }),
+ * );
+ *
+ * // Piped call
+ * const op = MyOp.pipe(Operation.withHandler((input) => Effect.succeed({})));
+ * ```
+ */
+export const withHandler: {
+  <Def extends Definition<any, any>, E = never>(
+    handler: Handler<Definition.Input<Def>, Definition.Output<Def>, E, Definition.Services<Def> | Service>,
+  ): (op: Def) => WithHandler<Def>;
+  <Def extends Definition<any, any>, E = never>(
+    op: Def,
+    handler: Handler<Definition.Input<Def>, Definition.Output<Def>, E, Definition.Services<Def> | Service>,
+  ): WithHandler<Def>;
+} = <Def extends Definition<any, any>, E = never>(
+  opOrHandler: Def | Handler<Definition.Input<Def>, Definition.Output<Def>, E, Definition.Services<Def> | Service>,
+  handler?: Handler<Definition.Input<Def>, Definition.Output<Def>, E, Definition.Services<Def> | Service>,
+): WithHandler<Def> => {
+  // If called with just handler (piped usage).
+  if (handler === undefined) {
+    const handlerFn = opOrHandler as Handler<
+      Definition.Input<Def>,
+      Definition.Output<Def>,
+      E,
+      Definition.Services<Def> | Service
+    >;
+    return ((op: Def) => ({
+      ...op,
+      handler: handlerFn,
+    })) as any;
+  }
+
+  // If called with both op and handler (direct usage).
+  const op = opOrHandler as Def;
+  return {
+    ...op,
+    handler,
+  } as any;
+};
+
+/**
+ * Helper to make the handler type opaque.
+ * Workaround for TypeScript's inability to infer the handler type from the operation definition:
+ * ```
+ * error TS2742: The inferred type of 'default' cannot be named without a reference.
+ * ```
+ *
+ * Most of the time the exact handler type is not needed.
+ *
+ * @example
+ * ```ts
+ * const MyOp = Operation.make({
+ *   input: Schema.Void,
+ *   output: Schema.Void,
+ *   meta: { key: 'my-op' },
+ *   services: [DatabaseService],
+ * });
+ *
+ * export default MyOp.pipe(
+ *   Operation.withHandler(
+ *     Effect.fn(function* (input) {
+ *       return { result: 'ok' };
+ *     }),
+ *   ),
+ *   Operation.opaqueHandler,
+ * );
+ * ```
+ */
+export const opaqueHandler = <T extends Operation.Definition.Any>(
+  handler: Operation.WithHandler<T>,
+): Operation.WithHandler<Operation.Definition.Any> => handler;
+
+//
+// Invocation Interfaces
+//
+
+/**
+ * Local invocation of an operation.
+ */
+export type Invoke = <I, O, E>(op: Definition<I, O>, input: I) => Effect.Effect<O, E>;
+
+/**
+ * Remote invocation of an operation.
+ */
+export type InvokeRemote = <I, O, E>(
+  op: Definition<I, O>,
+  input: I,
+  options?: { timeout?: number },
+) => Effect.Effect<O, E>;
+
+/**
+ * Database record of an operation.
+ */
+export const PersistentOperation = Schema$.Struct({
+  /**
+   * Global registry ID.
+   * NOTE: The `key` property refers to the original registry entry.
+   */
+  // TODO(burdon): Create Format type for DXN-like ids, such as this and schema type.
+  // TODO(dmaretskyi): Consider making it part of ECHO meta.
+  // TODO(dmaretskyi): Make required.
+  key: Schema$.optional(Schema$.String).annotations({
+    description: 'Unique registration key for the blueprint',
+  }),
+
+  name: Schema$.NonEmptyString,
+  version: Schema$.String,
+
+  description: Schema$.optional(Schema$.String),
+
+  /**
+   * ISO date string of the last deployment.
+   */
+  updated: Schema$.optional(Schema$.String),
+
+  // Reference to a source script if it exists within ECHO.
+  // TODO(burdon): Don't ref ScriptType directly (core).
+  source: Schema$.optional(Ref.Ref(Obj.Unknown)),
+
+  inputSchema: Schema$.optional(JsonSchema.JsonSchema),
+  outputSchema: Schema$.optional(JsonSchema.JsonSchema),
+
+  /**
+   * List of required services.
+   * Match the Context.Tag keys of the FunctionServices variants.
+   */
+  services: Schema$.optional(Schema$.Array(Schema$.String)),
+
+  // Local binding to a function name.
+  // TODO(dmaretskyi): Add this field to Operation.Definition.
+  binding: Schema$.optional(Schema$.String),
+}).pipe(
+  // TODO(dmaretskyi): Keep typename as 'org.dxos.type.function' (not 'operation') to maintain
+  //  backward compatibility with existing data and avoid requiring data migration.
+  Type.object({
+    typename: 'org.dxos.type.function',
+    version: '0.1.0',
+  }),
+  Annotation.LabelAnnotation.set(['name']),
+  Annotation.IconAnnotation.set({ icon: 'ph--function--regular', hue: 'blue' }),
+  Annotation.SystemTypeAnnotation.set(true),
+);
+export interface PersistentOperation extends Schema$.Schema.Type<typeof PersistentOperation> {}
+
+/**
+ * Serialize an operation definition to a persistent operation record.
+ */
+export const serialize = (operation: Definition.Any): PersistentOperation => {
+  return Obj.make(PersistentOperation, {
+    key: operation.meta.key,
+    name: operation.meta.name ?? '',
+    version: operation.meta.version ?? '0.0.0',
+    description: operation.meta.description,
+    updated: undefined,
+    source: undefined,
+    inputSchema: JsonSchema.toJsonSchema(operation.input),
+    outputSchema: JsonSchema.toJsonSchema(operation.output),
+    services: operation.services.map((service) => service.key),
+  });
+};
+
+/**
+ * Deserialize a persistent operation record to an operation definition.
+ */
+export const deserialize = (record: PersistentOperation): Definition.Any => {
+  // Extract deployed function ID from ECHO meta keys (matches FUNCTIONS_META_KEY in @dxos/functions).
+  const deployedId = Obj.getMeta(record).keys.find((key) => key.source === 'org.dxos.service.function')?.id;
+  return make({
+    input: record.inputSchema ? JsonSchema.toEffectSchema(record.inputSchema) : Schema$.Unknown,
+    output: record.outputSchema ? JsonSchema.toEffectSchema(record.outputSchema) : Schema$.Unknown,
+    services: record.services?.map((service) => Context.GenericTag(service)) ?? [],
+    executionMode: 'async',
+    types: [],
+    meta: {
+      key: record.key ?? record.name,
+      name: record.name,
+      version: record.version,
+      description: record.description,
+      deployedId,
+    },
+  });
+};
+
+/**
+ * Update properties on the target operation record from the source operation record.
+ */
+export const setFrom = (target: PersistentOperation, source: PersistentOperation) => {
+  Obj.update(target, (target) => {
+    target.key = source.key ?? target.key;
+    target.name = source.name ?? target.name;
+    target.version = source.version;
+    target.description = source.description;
+    target.updated = source.updated;
+    // TODO(dmaretskyi): A workaround for an ECHO bug.
+    target.inputSchema = source.inputSchema ? JSON.parse(JSON.stringify(source.inputSchema)) : undefined;
+    target.outputSchema = source.outputSchema ? JSON.parse(JSON.stringify(source.outputSchema)) : undefined;
+    Obj.getMeta(target).keys = JSON.parse(JSON.stringify(Obj.getMeta(source).keys));
+  });
+};
+
+/**
+ * Options for operation invocation.
+ */
+export interface InvokeOptions {
+  /**
+   * Space ID to provide database context for the handler.
+   */
+  spaceId?: Key.SpaceId;
+  /**
+   * DXN string of the conversation feed (queue).
+   * Passed to the process environment so nested operations can resolve AiContextService and related services.
+   */
+  conversation?: DXN.String;
+  /**
+   * Optional process-runtime tracing metadata (consumed by `@dxos/functions-runtime` when wired).
+   */
+  tracing?: unknown;
+}
+
+/**
+ * Operation service interface - provides unified access to operation invocation and scheduling.
+ * This service is automatically provided to operation handlers.
+ */
+export interface OperationService {
+  /**
+   * Invoke an operation as an Effect.
+   * Returns an Effect that resolves to the operation output.
+   */
+  invoke: <I, O>(
+    op: Operation.Definition<I, O>,
+    ...args: void extends I ? [input?: I, options?: InvokeOptions] : [input: I, options?: InvokeOptions]
+  ) => Effect.Effect<O, NoHandlerError>;
+
+  /**
+   * Schedule an operation to run as a followup.
+   * The followup is tracked and won't be cancelled when the parent operation completes.
+   * Returns an Effect that completes immediately after scheduling.
+   */
+  schedule: <I, O>(
+    op: Operation.Definition<I, O>,
+    ...args: void extends I ? [input?: I] : [input: I]
+  ) => Effect.Effect<void>;
+
+  /**
+   * Invoke an operation and return a Promise.
+   * Useful for async contexts where Effect is not available.
+   */
+  invokePromise: <I, O>(
+    op: Operation.Definition<I, O>,
+    ...args: void extends I ? [input?: I, options?: InvokeOptions] : [input: I, options?: InvokeOptions]
+  ) => Promise<{ data?: O; error?: Error }>;
+}
+
+/**
+ * Context tag for the Operation service.
+ * Operation handlers can yield this to invoke other operations or schedule followups.
+ *
+ * @example
+ * ```ts
+ * const handler = (input) => Effect.gen(function* () {
+ *   // Schedule a followup (fire and forget)
+ *   yield* Operation.schedule(AnalyticsOperation, { event: 'completed' });
+ *
+ *   // Invoke another operation
+ *   return yield* Operation.invoke(OtherOperation, { data: input.data });
+ * });
+ * ```
+ */
+// TODO(dmaretskyi): Rename Operation.Invoker
+export class Service extends Context.Tag('@dxos/operation/Service')<Service, OperationService>() {}
+
+//
+// Namespace functions - ergonomic access to Operation.Service methods.
+//
+
+/**
+ * Invoke an operation as an Effect.
+ * Yields the Operation.Service internally.
+ *
+ * @example
+ * ```ts
+ * yield* Operation.invoke(MyOperation, { data: 'test' });
+ * ```
+ */
+export const invoke = <I, O>(
+  op: Operation.Definition<I, O>,
+  ...args: void extends I ? [input?: I, options?: InvokeOptions] : [input: I, options?: InvokeOptions]
+): Effect.Effect<O, NoHandlerError, Service> =>
+  Effect.flatMap(Service, (ops) => ops.invoke(op, ...(args as [I, InvokeOptions?]))).pipe(
+    Effect.withSpan('Operation.invoke'),
+  );
+
+/**
+ * Schedule an operation to run as a followup.
+ * Yields the Operation.Service internally.
+ *
+ * @example
+ * ```ts
+ * yield* Operation.schedule(AnalyticsOperation, { event: 'completed' });
+ * yield* Operation.schedule(VoidOperation); // input optional when void
+ * ```
+ */
+export const schedule = <I, O>(
+  op: Operation.Definition<I, O>,
+  ...args: void extends I ? [input?: I] : [input: I]
+): Effect.Effect<void, never, Service> =>
+  Effect.flatMap(Service, (ops) => ops.schedule(op, args[0] as I)).pipe(Effect.withSpan('Operation.schedule'));
+
+/**
+ * Provides additional invocation options to all invocations.
+ */
+export const withInvocationOptions = (options: InvokeOptions): Layer.Layer<Service, never, Service> =>
+  Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const service = yield* Service;
+      return Service.of({
+        invoke: ((op: Operation.Definition.Any, input: any, invocationOptions: InvokeOptions) =>
+          service.invoke(op, input, { ...options, ...invocationOptions })) as any,
+        invokePromise: ((op: Operation.Definition.Any, input: any, invocationOptions: InvokeOptions) =>
+          service.invokePromise(op, input, { ...options, ...invocationOptions })) as any,
+        schedule: service.schedule,
+      });
+    }),
+  );

package/src/OperationHandlerSet.ts

@@ -0,0 +1,132 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { assertArgument } from '@dxos/invariant';
+
+import { NoHandlerError } from './errors';
+import type * as Operation from './Operation';
+
+export const TypeId = '~@dxos/operation/OperationHandlerSet' as const;
+export type TypeId = typeof TypeId;
+
+export interface OperationHandlerSet {
+  [TypeId]: TypeId;
+
+  readonly handlers: Effect.Effect<Operation.WithHandler<Operation.Definition.Any>[]>;
+
+  getHandlers(): Promise<Operation.WithHandler<Operation.Definition.Any>[]>;
+}
+
+export const isOperationHandlerSet = (value: unknown): value is OperationHandlerSet => {
+  return typeof value === 'object' && value !== null && TypeId in value;
+};
+
+export const empty: OperationHandlerSet = {
+  [TypeId]: TypeId,
+  handlers: Effect.succeed([]),
+  getHandlers: () => Promise.resolve([]),
+};
+
+/**
+ * Creates a new operation handler set from a list of handlers.
+ *
+ * @example
+ * ```ts
+ * const set = OperationHandlerSet.make(
+ *   Operation.withHandler(Operation.make({ input: Schema.Void, output: Schema.Void }), (input) => Effect.succeed({})),
+ *   Operation.withHandler(Operation.make({ input: Schema.Void, output: Schema.Void }), (input) => Effect.succeed({})),
+ * );
+ * ```
+ */
+export const make = (...handlers: Operation.WithHandler<Operation.Definition.Any>[]): OperationHandlerSet => {
+  return async(() => Promise.resolve(handlers));
+};
+
+export const async = (
+  getHandlers: () => Promise<Operation.WithHandler<Operation.Definition.Any>[]>,
+): OperationHandlerSet => {
+  // NOTE: Re-runing async module imports has a big performance penalty in Chrome.
+  let promise: Promise<Operation.WithHandler<Operation.Definition.Any>[]> | null = null;
+  const getHandlersCached = () => {
+    if (!promise) {
+      promise = getHandlers();
+    }
+    return promise;
+  };
+  return {
+    [TypeId]: TypeId,
+    getHandlers,
+    handlers: Effect.promise(getHandlersCached),
+  };
+};
+
+/**
+ * Merges multiple operation handler sets into a single set.
+ *
+ */
+export const merge = (...sets: OperationHandlerSet[]): OperationHandlerSet => {
+  assertArgument(sets.every(isOperationHandlerSet), 'sets', 'sets must be an array of OperationHandlerSet');
+  return async(() => Promise.all(sets.map((set) => set.getHandlers())).then((handlers) => handlers.flat()));
+};
+
+/**
+ * Creates a new operation handler set from a list of lazy-loaded modules.
+ *
+ * @example
+ * ```ts
+ * const set = OperationHandlerSet.lazy(
+ *   () => import('./my-handler'),
+ *   () => import('./my-other-handler'),
+ * );
+ * ```
+ */
+export const lazy = (
+  ...modules: (() => Promise<{ default: Operation.WithHandler<Operation.Definition.Any> }>)[]
+): OperationHandlerSet => {
+  return async(() => Promise.all(modules.map((module) => module().then(({ default: handler }) => handler))));
+};
+
+/**
+ * Gets a handler for an operation by definition.
+ */
+export const getHandler = <const Op extends Operation.Definition.Any>(
+  set: OperationHandlerSet,
+  definition: Op,
+): Effect.Effect<Operation.WithHandler<Op>, NoHandlerError> =>
+  Effect.gen(function* () {
+    const handlers = yield* set.handlers;
+    const handler = handlers.find((handler) => handler.meta.key === definition.meta.key);
+    if (!handler) {
+      return yield* Effect.fail(new NoHandlerError(definition.meta.key));
+    }
+    return handler as any;
+  });
+
+/**
+ * Gets a handler for an operation by key.
+ */
+export const getHandlerByKey = (
+  set: OperationHandlerSet,
+  key: string,
+): Effect.Effect<Operation.WithHandler<Operation.Definition.Any>, NoHandlerError> =>
+  Effect.gen(function* () {
+    const handlers = yield* set.handlers;
+    const handler = handlers.find((handler) => handler.meta.key === key);
+    if (!handler) {
+      return yield* Effect.fail(new NoHandlerError(key));
+    }
+    return handler as any;
+  });
+
+export class OperationHandlerProvider extends Context.Tag('@dxos/operation/OperationHandlerProvider')<
+  OperationHandlerProvider,
+  OperationHandlerSet
+>() {}
+
+export const provide = (handlers: OperationHandlerSet): Layer.Layer<OperationHandlerProvider, never, never> =>
+  Layer.succeed(OperationHandlerProvider, handlers);

package/src/OperationRegistry.ts

@@ -0,0 +1,48 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+
+import { Database, Query } from '@dxos/echo';
+
+import * as Operation from './Operation';
+import * as OperationHandlerSet from './OperationHandlerSet';
+
+export interface OperationRegistry {
+  /**
+   * Resolve an operation by key.
+   */
+  resolve(key: string): Effect.Effect<Option.Option<Operation.Definition.Any>>;
+}
+
+export class Service extends Context.Tag('@dxos/operation/OperationRegistry')<Service, OperationRegistry>() {}
+
+/**
+ * Resolve an operation by key.
+ */
+export const resolve: (key: string) => Effect.Effect<Option.Option<Operation.Definition.Any>, never, Service> =
+  Effect.serviceFunctionEffect(Service, (service) => service.resolve);
+
+export const layer: Layer.Layer<Service, never, Database.Service | OperationHandlerSet.OperationHandlerProvider> =
+  Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const database = yield* Database.Service;
+      const handlerSet = yield* OperationHandlerSet.OperationHandlerProvider;
+      return {
+        resolve: (key: string) =>
+          Database.runQueryFirst(Query.type(Operation.PersistentOperation, { key }))
+            .pipe(
+              Effect.flatten,
+              Effect.map(Operation.deserialize),
+              Effect.catchTag('NoSuchElementException', () => OperationHandlerSet.getHandlerByKey(handlerSet, key)),
+              Effect.option,
+            )
+            .pipe(Effect.provideService(Database.Service, database)),
+      };
+    }),
+  );