@dxos/compute 0.8.4-main.fd6878d → 0.9.0

package/src/ServiceResolver.ts

@@ -0,0 +1,200 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Either from 'effect/Either';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import * as Scope from 'effect/Scope';
+
+import type { SpaceId, URI } from '@dxos/keys';
+
+import { ServiceNotAvailableError } from './errors';
+import * as Process from './Process';
+
+const ServiceResolverTypeId = '~@dxos/functions/ServiceResolver' as const;
+type ServiceResolverTypeId = typeof ServiceResolverTypeId;
+
+export interface ServiceResolver {
+  readonly [ServiceResolverTypeId]: ServiceResolverTypeId;
+
+  /**
+   * Resolve a set of services identified by their tags.
+   * Returns a Context containing all requested services, or fails with ServiceNotAvailableError.
+   */
+  resolve<Tag extends Context.Tag<any, any>>(
+    tag: Tag,
+    context: ResolutionContext,
+  ): Effect.Effect<Context.Tag.Service<Tag>, ServiceNotAvailableError, Scope.Scope>;
+}
+
+/**
+ * Tag for the ServiceResolver service.
+ */
+export const ServiceResolver = Context.GenericTag<ServiceResolver>('@dxos/functions/ServiceResolver');
+
+export const resolve: {
+  <Tag extends Context.Tag<any, any>>(
+    tag: Tag,
+    context: ResolutionContext,
+  ): Effect.Effect<Context.Tag.Service<Tag>, ServiceNotAvailableError, Scope.Scope | ServiceResolver>;
+} = Effect.serviceFunctionEffect(ServiceResolver, (_) => _.resolve);
+
+export const resolveAll = <const Tags extends readonly Context.Tag<any, any>[]>(
+  tags: Tags,
+  context: ResolutionContext,
+): Effect.Effect<Context.Context<Tags[number]>, ServiceNotAvailableError, Scope.Scope | ServiceResolver> =>
+  Effect.gen(function* () {
+    const services = yield* Effect.forEach(tags, (tag) =>
+      resolve(tag, context).pipe(Effect.map((service) => Context.make(tag, service))),
+    );
+    return Context.mergeAll(...services);
+  });
+
+/**
+ * Provides context for service resolution.
+ */
+export interface ResolutionContext {
+  /**
+   * Under which identity the process is running.
+   */
+  readonly identity?: string;
+
+  /**
+   * Under which space the process is running.
+   */
+  readonly space?: SpaceId;
+
+  /**
+   * URI of the conversation feed the process is running in. Today always an EID;
+   * narrow with `EID.parse` at the point of use.
+   */
+  readonly conversation?: URI.URI;
+
+  /**
+   * Under which process the process is running.
+   */
+  readonly process?: Process.ID;
+}
+
+export const succeed = <I, S>(
+  tag: Context.Tag<I, S>,
+  getService: (context: ResolutionContext) => Effect.Effect<S, ServiceNotAvailableError, Scope.Scope>,
+): ServiceResolver => {
+  return make((tag1, context) => {
+    if (tag1.key !== tag.key) {
+      return Effect.fail(new ServiceNotAvailableError(`Service not available: ${String(tag.key ?? tag)}`));
+    }
+    const service = getService(context);
+    return service as any;
+  });
+};
+
+/**
+ * Create a ServiceResolver from a custom resolution function.
+ */
+export const make = (
+  resolveFn: <I, S>(
+    tag: Context.Tag<I, S>,
+    context: ResolutionContext,
+  ) => Effect.Effect<S, ServiceNotAvailableError, Scope.Scope>,
+): ServiceResolver => ({
+  [ServiceResolverTypeId]: ServiceResolverTypeId,
+  resolve: resolveFn,
+});
+
+/**
+ * Create a ServiceResolver backed by a static Context.
+ * Tags present in the context are resolved; missing tags fail with ServiceNotAvailableError.
+ */
+export const fromContext = <Services>(ctx: Context.Context<Services>): ServiceResolver =>
+  make((tag, context) =>
+    Effect.gen(function* () {
+      const service = Context.getOption(ctx, tag);
+      if (Option.isNone(service)) {
+        return yield* Effect.fail(new ServiceNotAvailableError(String(tag.key ?? tag)));
+      }
+      return service.value;
+    }),
+  );
+
+/**
+ * Create a ServiceResolver that resolves tags from the current Effect context.
+ * Only the specified tags are available; requests for other tags fail.
+ */
+export const fromRequirements = <const Tags extends readonly Context.Tag<any, any>[]>(
+  ...tags: Tags
+): Effect.Effect<ServiceResolver, never, Context.Tag.Identifier<Tags[number]>> =>
+  Effect.contextWith((parentCtx: Context.Context<any>) => {
+    const available = new Set(tags.map((tag) => tag.key));
+    return make((tag, context) =>
+      Effect.gen(function* () {
+        let result: Context.Context<never> = Context.empty() as Context.Context<never>;
+        if (!available.has(tag.key)) {
+          return yield* Effect.fail(new ServiceNotAvailableError(String(tag.key ?? tag)));
+        }
+        const service = Context.getOption(parentCtx, tag);
+        if (Option.isNone(service)) {
+          return yield* Effect.fail(new ServiceNotAvailableError(String(tag.key ?? tag)));
+        }
+        return service.value;
+      }),
+    );
+  });
+
+/**
+ * Like {@link fromRequirements} but returns a Layer that provides ServiceResolver.
+ */
+export const layerRequirements = <const Tags extends readonly Context.Tag<any, any>[]>(
+  ...tags: Tags
+): Layer.Layer<ServiceResolver, never, Context.Tag.Identifier<Tags[number]>> =>
+  Layer.effect(ServiceResolver, fromRequirements(...tags));
+
+/**
+ * Build a {@link Layer} that materialises the requested services by calling
+ * {@link resolveAll} against the {@link ServiceResolver} currently in context.
+ *
+ * The returned layer manages its own {@link Scope.Scope} and requires only a
+ * {@link ServiceResolver} (typically supplied by the process-manager runtime).
+ *
+ * @example
+ * ```ts
+ * processManagerRuntime.runPromise(
+ *   myEffect.pipe(Effect.provide(ServiceResolver.provide({ space }, Database.Service, Feed.FeedService))),
+ * );
+ * ```
+ */
+export const provide = <const Tags extends readonly Context.Tag<any, any>[]>(
+  context: ResolutionContext,
+  ...tags: Tags
+): Layer.Layer<Context.Tag.Identifier<Tags[number]>, ServiceNotAvailableError, ServiceResolver> =>
+  Layer.scopedContext(resolveAll(tags, context));
+
+/**
+ * Compose multiple resolvers left to right. Earlier resolvers take precedence:
+ * the first resolver that can satisfy a tag wins.
+ */
+export const compose = (...resolvers: readonly ServiceResolver[]): ServiceResolver =>
+  make((tag, context) =>
+    Effect.gen(function* () {
+      for (const resolver of resolvers) {
+        const single = yield* resolver.resolve(tag, context).pipe(Effect.either);
+        if (Either.isRight(single)) {
+          return single.right;
+        }
+      }
+
+      return yield* Effect.fail(new ServiceNotAvailableError(String(tag.key ?? tag)));
+    }),
+  );
+
+/**
+ * An empty resolver that fails for any requested service.
+ */
+export const empty: ServiceResolver = make((tag, context) => {
+  return Effect.fail(new ServiceNotAvailableError(String(tag.key ?? tag)));
+});

package/src/StorageService.ts

@@ -0,0 +1,101 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Pipeable from 'effect/Pipeable';
+import * as Schema from 'effect/Schema';
+
+export interface Service {
+  /** Read a value by key. Returns `None` if key does not exist. */
+  get<S extends Schema.Schema<any, string, any>>(
+    schema: S,
+    key: string,
+  ): Effect.Effect<Option.Option<Schema.Schema.Type<S>>, never, Schema.Schema.Context<S>>;
+
+  /** Write a value for the given key. */
+  set<S extends Schema.Schema<any, string, any>>(
+    schema: S,
+    key: string,
+    value: Schema.Schema.Type<S>,
+  ): Effect.Effect<void, never, Schema.Schema.Context<S>>;
+
+  /** Remove a key. */
+  delete(key: string): Effect.Effect<void>;
+
+  /** List all keys, optionally filtered by prefix. */
+  list(prefix?: string): Effect.Effect<readonly string[]>;
+
+  /** Remove all keys managed by this scoped store. */
+  clear(): Effect.Effect<void>;
+}
+
+/**
+ * Scoped key-value storage service for processes.
+ * Each process receives its own namespaced instance via the process manager.
+ * Construct a live implementation with `StorageService.layer` from `@dxos/functions-runtime`.
+ */
+export class StorageService extends Context.Tag('@dxos/functions/StorageService')<StorageService, Service>() {}
+
+export const get = Effect.serviceFunctionEffect(StorageService, (_) => _.get);
+export const set = Effect.serviceFunctionEffect(StorageService, (_) => _.set);
+export const deleteKey = Effect.serviceFunctionEffect(StorageService, (_) => _.delete);
+export const list = Effect.serviceFunctionEffect(StorageService, (_) => _.list);
+export const clear = Effect.serviceFunctionEffect(StorageService, (_) => _.clear);
+
+/**
+ * Typed key in a storage service.
+ */
+export interface Key<T> extends Pipeable.Pipeable {
+  readonly key: string;
+
+  get: Effect.Effect<Option.Option<T>, never, StorageService>;
+  set(value: T): Effect.Effect<void, never, StorageService>;
+  delete(): Effect.Effect<void, never, StorageService>;
+}
+
+/**
+ * Create a typed key in a storage service.
+ */
+export const key = <S extends Schema.Schema<any, string, any>>(schema: S, key: string): Key<Schema.Schema.Type<S>> => {
+  return {
+    key,
+    get: get(schema, key),
+    set: (value: Schema.Schema.Type<S>) => set(schema, key, value),
+    delete: () => deleteKey(key),
+    pipe(...args: any) {
+      return Pipeable.pipeArguments(this, arguments);
+    },
+  };
+};
+
+/**
+ * Typed key in a storage service with a default value.
+ */
+export interface KeyWithDefault<T, U> extends Pipeable.Pipeable {
+  readonly key: string;
+  get: Effect.Effect<T | U, never, StorageService>;
+  set(value: U): Effect.Effect<void, never, StorageService>;
+  delete(): Effect.Effect<void, never, StorageService>;
+}
+
+/**
+ * Assign a default value to a key if it is not present.
+ */
+export const withDefault =
+  <T>(getDefault: () => NoInfer<T>) =>
+  (key: Key<T>): KeyWithDefault<T, T> => {
+    return {
+      key: key.key,
+      get: key.get.pipe(Effect.map(Option.getOrElse(() => getDefault()))),
+      set: (value) => key.set(value),
+      delete: () => key.delete(),
+      pipe(...args: any) {
+        return Pipeable.pipeArguments(this, arguments);
+      },
+    };
+  };

package/src/Template.test.ts

@@ -0,0 +1,164 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import { describe, expect, test } from 'vitest';
+
+import { registryLayer } from '@dxos/echo-client';
+import { DXN } from '@dxos/keys';
+
+import { FunctionNotFoundError } from './errors';
+import * as Operation from './Operation';
+import * as Template from './Template';
+
+describe('Template', () => {
+  describe('make', () => {
+    test('creates a template with defaults', () => {
+      const template = Template.make();
+      expect(template.source).toBeDefined();
+      expect(template.inputs).toEqual([]);
+    });
+
+    test('wraps the source string as a Text ref', () => {
+      const template = Template.make({ source: 'Hello {{name}}.' });
+      expect(template.source.target?.content).toBe('Hello {{name}}.');
+    });
+
+    test('preserves inputs', () => {
+      const template = Template.make({
+        source: 'Hello {{name}}.',
+        inputs: [{ name: 'name', kind: 'value', default: 'world' }],
+      });
+      expect(template.inputs).toHaveLength(1);
+      expect(template.inputs?.[0]).toMatchObject({ name: 'name', kind: 'value', default: 'world' });
+    });
+  });
+
+  describe('schema', () => {
+    test('Template is a Schema', () => {
+      expect(Schema.isSchema(Template.Template)).toBe(true);
+    });
+
+    test('Input is a Schema', () => {
+      expect(Schema.isSchema(Template.Input)).toBe(true);
+    });
+
+    test('InputKind accepts all documented kinds', () => {
+      const decode = Schema.decodeSync(Template.InputKind);
+      for (const kind of ['value', 'operation']) {
+        expect(decode(kind as any)).toBe(kind);
+      }
+    });
+
+    test('InputKind rejects unknown kinds', () => {
+      expect(() => Schema.decodeSync(Template.InputKind)('nonsense' as any)).toThrow();
+    });
+  });
+
+  describe('process', () => {
+    test('substitutes simple variables', () => {
+      expect(Template.process('Hello {{name}}.', { name: 'world' })).toBe('Hello world.');
+    });
+
+    test('renders an empty variables object as empty placeholders', () => {
+      expect(Template.process('Hello {{name}}.')).toBe('Hello .');
+    });
+
+    test('trims leading and trailing whitespace', () => {
+      expect(Template.process('   \n\nHello.\n\n   ')).toBe('Hello.');
+    });
+
+    test('collapses runs of 3+ blank lines down to one blank line', () => {
+      const input = 'a\n\n\n\n\nb';
+      expect(Template.process(input)).toBe('a\n\nb');
+    });
+
+    test('preserves double newlines', () => {
+      expect(Template.process('a\n\nb')).toBe('a\n\nb');
+    });
+
+    test('{{section}} helper increments on each call', () => {
+      expect(Template.process('{{section}} / {{section}} / {{section}}')).toBe('1 / 2 / 3');
+    });
+  });
+
+  describe('processTemplate', () => {
+    const GREET_KEY = DXN.make('org.example.test.greet');
+
+    const greet = Operation.withHandler(
+      Operation.make({
+        input: Schema.Void,
+        output: Schema.String,
+        meta: { key: GREET_KEY, name: 'greet' },
+      }),
+      () => Effect.succeed('Alice'),
+    );
+
+    // Handler map: full DXN key → invocable function.
+    const handlersByKey: Record<string, (input: any) => Effect.Effect<any, any, any>> = {
+      [GREET_KEY]: (input) => greet.handler(input),
+    };
+
+    const stubInvoker = Effect.provideService(Operation.Service, {
+      invoke: (op: any, input: any) => {
+        const key = String(op.meta.key);
+        const handler = handlersByKey[key];
+        return handler ? handler(input) : Effect.die(`no handler for key: ${key}`);
+      },
+      schedule: () => Effect.succeed(undefined),
+      invokePromise: () => Promise.resolve({}),
+      // Operation.OperationService.invoke is a complex overloaded type; a partial test stub
+      // cannot express all overload variants without the cast.
+    } as unknown as Operation.OperationService);
+
+    test('resolves a value-kind input from its default', async () => {
+      const template = Template.make({
+        source: 'Hello {{name}}!',
+        inputs: [{ name: 'name', kind: 'value', default: 'world' }],
+      });
+
+      const result = await Template.processTemplate(template).pipe(
+        Effect.provide(registryLayer()),
+        stubInvoker,
+        Effect.runPromise,
+      );
+      expect(result).toBe('Hello world!');
+    });
+
+    test('resolves an operation-kind input and substitutes the result', async () => {
+      const template = Template.make({
+        source: 'Hello {{name}}.',
+        inputs: [{ name: 'name', kind: 'operation', operation: GREET_KEY }],
+      });
+
+      const result = await Template.processTemplate(template).pipe(
+        Effect.provide(registryLayer({ initial: [Operation.serialize(greet)] })),
+        stubInvoker,
+        Effect.runPromise,
+      );
+
+      expect(result).toBe('Hello Alice.');
+    });
+
+    test('fails with FunctionNotFoundError when the function key cannot be resolved', async () => {
+      const template = Template.make({
+        source: 'Hello {{name}}.',
+        inputs: [{ name: 'name', kind: 'operation', operation: 'test.missing' }],
+      });
+
+      const result = await Template.processTemplate(template).pipe(
+        Effect.provide(registryLayer()),
+        stubInvoker,
+        Effect.either,
+        Effect.runPromise,
+      );
+
+      expect(result._tag).toBe('Left');
+      if (result._tag === 'Left') {
+        expect(result.left).toBeInstanceOf(FunctionNotFoundError);
+      }
+    });
+  });
+});

package/src/Template.ts

@@ -0,0 +1,125 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Database, DXN, Filter, Ref, Registry } from '@dxos/echo';
+import type { EntityNotFoundError } from '@dxos/echo/Err';
+import { assertArgument, invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { Text } from '@dxos/schema';
+import Handlebars from '@dxos/vendor-kbn-handlebars';
+
+import { FunctionNotFoundError } from './errors';
+import * as Operation from './Operation';
+
+/**
+ * Template input kind determines how template variables are resolved.
+ */
+export const InputKind = Schema.Literal(
+  'value', // Literal value.
+  'operation',
+  // 'pass-through',
+  // 'retriever',
+  // 'query',
+  // 'resolver',
+  // 'context',
+  // 'schema',
+);
+
+export type InputKind = Schema.Schema.Type<typeof InputKind>;
+
+/**
+ * Template input variable.
+ * E.g., {{foo}}
+ */
+export const Input = Schema.Struct({
+  name: Schema.String,
+  kind: InputKind,
+  default: Schema.optional(Schema.Any),
+  /**
+   * Operation key invoked when `kind === 'operation'`. The referenced operation must accept void input —
+   * template inputs have no mechanism for passing arguments.
+   */
+  operation: Schema.optional(Schema.String),
+});
+
+export type Input = Schema.Schema.Type<typeof Input>;
+
+/**
+ * Template type.
+ */
+export const Template = Schema.Struct({
+  source: Ref.Ref(Text.Text).annotations({ description: 'Markdown + Handlebars template.' }),
+
+  /**
+   * NOTE: We use an array rather than map so that updating variable names in the template doesn't disconnect existing inputs.
+   */
+  inputs: Schema.optional(Schema.Array(Input)),
+});
+
+export type Template = Schema.Schema.Type<typeof Template>;
+export type MakeProps = Partial<{ id: string; source: string; inputs: Input[] }>;
+
+export const make = ({ id, source, inputs = [] }: MakeProps = {}): Template => ({
+  source: Ref.make(Text.make({ id, content: source })),
+  inputs,
+});
+
+/**
+ * Process Handlebars template.
+ */
+export const process = <Options extends {}>(source: string, variables: Partial<Options> = {}): string => {
+  assertArgument(typeof source === 'string', 'source');
+  let section = 0;
+  const handlebars = Handlebars.create();
+  handlebars.registerHelper('section', () => String(++section));
+  const template = handlebars.compileAST(source.trim());
+  const output = template(variables);
+  return output.trim().replace(/(\n\s*){3,}/g, '\n\n');
+};
+
+export const processTemplate = (
+  template: Template,
+): Effect.Effect<string, EntityNotFoundError | FunctionNotFoundError, Registry.Service | Operation.Service> =>
+  Effect.gen(function* () {
+    const entries = yield* Effect.forEach(template.inputs ?? [], (input) =>
+      Effect.gen(function* () {
+        switch (input.kind) {
+          case 'value': {
+            return [input.name, input.default] as const;
+          }
+
+          case 'operation': {
+            invariant(input.operation);
+            // Normalize to a full DXN key so Filter.key matches the stored meta key.
+            const key = DXN.isDXN(input.operation) ? input.operation : `dxn:${input.operation}`;
+            const results = yield* Registry.runQuery(
+              Filter.and(Filter.type(Operation.PersistentOperation), Filter.key(key)),
+            );
+            if (results.length === 0) {
+              return yield* Effect.fail(new FunctionNotFoundError(input.operation));
+            }
+            const fn = Operation.deserialize(results[0]);
+
+            // NOTE: Operations referenced by template inputs must accept void input — see `Input.operation`.
+            const result = yield* Operation.invoke(fn, undefined as any).pipe(Effect.orDie);
+            return [input.name, result] as const;
+          }
+
+          default: {
+            return yield* Effect.dieMessage(`Unsupported input kind: ${input.kind}`);
+          }
+        }
+      }),
+    );
+
+    const variables = Object.fromEntries(entries);
+
+    log('processTemplate', { variables });
+    return process((yield* Database.load(template.source)).content, variables);
+  });