@dxos/app-framework 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/plugin-process-manager/history/undo-registry.test.ts

@@ -0,0 +1,74 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { DXN } from '@dxos/keys';
+
+import { Compute, HalveCompute } from '../testing';
+import * as UndoMapping from './undo-mapping';
+import * as UndoRegistry from './undo-registry';
+
+describe('UndoRegistry', () => {
+  test('looks up undo mapping by operation key', ({ expect }) => {
+    const undoMapping = UndoMapping.make({
+      operation: Compute,
+      inverse: HalveCompute,
+      deriveContext: (_input, output) => ({ value: output.value }),
+    });
+    const registry = UndoRegistry.make(() => [undoMapping]);
+
+    const result = registry.lookup(Compute);
+    expect(result).not.toBe(undefined);
+    expect(result?.inverse.meta.key).toBe(DXN.make('org.dxos.test.halveCompute'));
+  });
+
+  test('returns undefined for unmapped operations', ({ expect }) => {
+    const registry = UndoRegistry.make(() => []);
+
+    const result = registry.lookup(Compute);
+    expect(result).toBe(undefined);
+  });
+
+  test('deriveContext extracts correct undo input', ({ expect }) => {
+    const undoMapping = UndoMapping.make({
+      operation: Compute,
+      inverse: HalveCompute,
+      // Note: This tests that input and output types are inferred correctly.
+      deriveContext: (input, output) => ({ value: output.value + input.value }),
+    });
+    const registry = UndoRegistry.make(() => [undoMapping]);
+
+    const result = registry.lookup(Compute);
+    const context = result?.deriveContext({ value: 5 }, { value: 10 });
+    expect(context).toEqual({ value: 15 });
+  });
+});
+
+describe('resolveMessage', () => {
+  test('returns undefined for undefined message', ({ expect }) => {
+    const result = UndoMapping.resolveMessage(undefined, { value: 1 }, { value: 2 });
+    expect(result).toBe(undefined);
+  });
+
+  test('returns static label as-is', ({ expect }) => {
+    const staticMessage: [string, { ns: string }] = ['test.message', { ns: 'test' }];
+    const result = UndoMapping.resolveMessage(staticMessage, { value: 1 }, { value: 2 });
+    expect(result).toEqual(staticMessage);
+  });
+
+  test('calls function message with input and output', ({ expect }) => {
+    const messageFunc = (input: { value: number }, output: { value: number }): [string, { ns: string }] => [
+      `input-${input.value}-output-${output.value}`,
+      { ns: 'test' },
+    ];
+    const result = UndoMapping.resolveMessage(messageFunc, { value: 5 }, { value: 10 });
+    expect(result).toEqual(['input-5-output-10', { ns: 'test' }]);
+  });
+
+  test('returns string label as-is', ({ expect }) => {
+    const result = UndoMapping.resolveMessage('simple string', { value: 1 }, { value: 2 });
+    expect(result).toBe('simple string');
+  });
+});

package/src/plugin-process-manager/history/undo-registry.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { Operation } from '@dxos/compute';
+
+import type * as UndoMapping from './undo-mapping';
+
+//
+// Public Interface
+//
+
+/**
+ * Lookup result from UndoRegistry.
+ */
+export type UndoMappingResult = {
+  inverse: Operation.Definition<any, any>;
+  /** Returns undefined to indicate the operation is not undoable. */
+  deriveContext: (input: any, output: any) => any | undefined;
+  /** Message provider - may be a static Label or a function. */
+  message?: UndoMapping.MessageProvider<Operation.Definition<any, any>>;
+};
+
+/**
+ * UndoRegistry interface - looks up inverse operations.
+ */
+export interface UndoRegistry {
+  lookup: (operation: Operation.Definition<any, any>) => UndoMappingResult | undefined;
+}
+
+//
+// Factory
+//
+
+/**
+ * Creates an UndoRegistry that looks up inverse operations.
+ */
+export const make = (getMappings: () => UndoMapping.UndoMapping[]): UndoRegistry => {
+  const lookup = (operation: Operation.Definition<any, any>): UndoMappingResult | undefined => {
+    const mappings = getMappings();
+    const mapping = mappings.find((m) => m.operation.meta.key === operation.meta.key);
+    if (!mapping) {
+      return undefined;
+    }
+
+    return {
+      inverse: mapping.inverse,
+      deriveContext: mapping.deriveContext,
+      message: mapping.message,
+    };
+  };
+
+  return { lookup };
+};

package/src/plugin-process-manager/idb-key-value-store.ts

@@ -0,0 +1,64 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as PlatformError from '@effect/platform/Error';
+import * as KeyValueStore from '@effect/platform/KeyValueStore';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import * as idb from 'idb-keyval';
+
+const DB_NAME = 'dxos-process-manager';
+const STORE_NAME = 'keyval';
+
+const idbError = (method: string, key: string, cause: unknown) =>
+  new PlatformError.SystemError({
+    reason: 'Unknown',
+    module: 'KeyValueStore',
+    method,
+    pathOrDescriptor: key,
+    description: String(cause),
+  });
+
+/**
+ * KeyValueStore layer backed by IndexedDB via idb-keyval.
+ * Uses a dedicated IDB database (dxos-process-manager) so process records
+ * survive page reloads without consuming the 5 MB localStorage quota.
+ * Falls back to an in-memory store in environments without IndexedDB (e.g. Node.js tests).
+ */
+export const layerIdb: Layer.Layer<KeyValueStore.KeyValueStore> =
+  typeof globalThis.indexedDB !== 'undefined'
+    ? Layer.sync(KeyValueStore.KeyValueStore, () => {
+        const store = idb.createStore(DB_NAME, STORE_NAME);
+        return KeyValueStore.makeStringOnly({
+          get: (key) =>
+            Effect.tryPromise({
+              try: () => idb.get<string>(key, store).then(Option.fromNullable),
+              catch: (err) => idbError('get', key, err),
+            }),
+
+          set: (key, value) =>
+            Effect.tryPromise({
+              try: () => idb.set(key, value, store),
+              catch: (err) => idbError('set', key, err),
+            }),
+
+          remove: (key) =>
+            Effect.tryPromise({
+              try: () => idb.del(key, store),
+              catch: (err) => idbError('remove', key, err),
+            }),
+
+          clear: Effect.tryPromise({
+            try: () => idb.clear(store),
+            catch: (err) => idbError('clear', '', err),
+          }),
+
+          size: Effect.tryPromise({
+            try: () => idb.keys(store).then((ks) => ks.length),
+            catch: (err) => idbError('size', '', err),
+          }),
+        });
+      })
+    : KeyValueStore.layerMemory;

package/src/plugin-process-manager/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './history';
+export * from './ProcessManagerPlugin';

package/src/plugin-process-manager/meta.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { DXN } from '@dxos/keys';
+
+import { Plugin } from '../core';
+
+export const meta = Plugin.makeMeta({
+  key: DXN.make('org.dxos.plugin.processManager'),
+  name: 'Process Manager Plugin',
+  author: 'DXOS',
+  description:
+    'Hosts the process-manager runtime that composes contributed layer specs into a service resolver, exposes the operation invoker built on top of it, and registers undo/history tracking.',
+  tags: ['system'],
+});

package/src/plugin-process-manager/process-manager-capability.ts

@@ -0,0 +1,178 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry } from '@effect-atom/atom';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+
+import { LayerSpec, OperationHandlerSet, Process, ServiceResolver, Trace } from '@dxos/compute';
+import { LayerStack, ProcessManager } from '@dxos/compute-runtime';
+import { invariant } from '@dxos/invariant';
+// Explicit import so the emitted `.d.ts` references the package via its public
+// alias instead of a relative `node_modules` path (TS2883).
+import { OperationInvoker } from '@dxos/operation';
+
+import { ActivationEvents, Capabilities } from '../common';
+import { Capability, Plugin } from '../core';
+import { layerIdb } from './idb-key-value-store';
+
+//
+// Capability Module
+//
+// Hosts the {@link ProcessManager} runtime for the plugin system.
+//
+// Workflow:
+// 1. Activates {@link ActivationEvents.SetupProcessManager} so plugins can
+//    contribute {@link Capabilities.LayerSpec} entries and
+//    {@link Capabilities.OperationHandler} sets.
+// 2. Collects all contributed {@link LayerSpec.LayerSpec}s and builds a
+//    {@link LayerStack} whose {@link ServiceResolver} drives process-scoped
+//    service resolution.
+// 3. Wires a reactive {@link OperationHandlerSet} that tracks
+//    {@link Capabilities.OperationHandler} contributions and invalidates its
+//    cached merge when new handlers register.
+// 4. Composes the fixed runtime requirements (capability/plugin managers,
+//    service resolver, operation invoker, process manager) into a single
+//    {@link Layer} and builds a {@link ManagedRuntime} from it.
+// 5. Exposes a disposable-less wrapper as {@link Capabilities.ProcessManagerRuntime}
+//    (the plugin system manages its lifecycle).
+//
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const capabilityManager = yield* Capability.Service;
+    const pluginManager = yield* Plugin.Service;
+    const atomRegistry = yield* Capability.get(Capabilities.AtomRegistry);
+
+    yield* Plugin.activate(ActivationEvents.SetupProcessManager);
+
+    const layerSpecs = yield* Capability.getAll(Capabilities.LayerSpec);
+    const traceSinkFactories = yield* Capability.getAll(Capabilities.TraceSink);
+
+    // Forward reference to `ProcessManager.ProcessManagerService`. The runtime
+    // that owns the manager depends transitively on `ServiceResolver` (which is
+    // built from the `LayerStack` below), so we cannot materialise it before
+    // the stack exists. Instead we publish the manager into this holder as
+    // soon as the runtime is built, and the ambient layer reads it lazily via
+    // `Layer.effect` — slice init only runs once a process actually triggers
+    // service resolution, by which point the holder is populated.
+    let processManagerHolder: ProcessManager.Manager | undefined;
+
+    // Expose the foundational app-framework services through the LayerStack so
+    // that operations declaring `services: [Capability.Service]` (and friends)
+    // can resolve them via the ServiceResolver. Without this, only consumers
+    // sitting on the same ManagedRuntime layer graph can see them — process
+    // executions go through ServiceResolver.resolveAll and would fail.
+    const ambientLayerSpec = LayerSpec.make(
+      {
+        affinity: 'application',
+        requires: [],
+        provides: [Capability.Service, Plugin.Service, Registry.AtomRegistry, ProcessManager.ProcessManagerService],
+      },
+      () =>
+        Layer.mergeAll(
+          Layer.succeed(Capability.Service, capabilityManager),
+          Layer.succeed(Plugin.Service, pluginManager),
+          Layer.succeed(Registry.AtomRegistry, atomRegistry),
+          Layer.effect(
+            ProcessManager.ProcessManagerService,
+            Effect.sync(() => {
+              invariant(
+                processManagerHolder,
+                'ProcessManagerService accessed before the process-manager runtime was initialised',
+              );
+              return processManagerHolder;
+            }),
+          ),
+        ),
+    );
+
+    const layerStack = new LayerStack.LayerStack({ layers: [ambientLayerSpec, ...layerSpecs] });
+    const serviceResolver = layerStack.getServiceResolver();
+
+    const handlerSet = OperationHandlerSet.reactive(
+      atomRegistry,
+      capabilityManager.atom(Capabilities.OperationHandler),
+    );
+
+    const traceSinks = traceSinkFactories.map((factory) => factory({ resolver: serviceResolver }));
+    const mergedTraceSink = Trace.mergeSinks(traceSinks);
+
+    // Base services required by ProcessManager and the operation invoker.
+    // Sensible defaults are provided here; plugins that want alternative
+    // implementations (e.g. persistent KV store, real tracing) can contribute
+    // their own LayerSpec entries against the ServiceResolver.
+    const baseLayer = Layer.mergeAll(
+      Layer.succeed(Capability.Service, capabilityManager),
+      Layer.succeed(Plugin.Service, pluginManager),
+      Layer.succeed(Registry.AtomRegistry, atomRegistry),
+      Layer.succeed(ServiceResolver.ServiceResolver, serviceResolver),
+      OperationHandlerSet.provide(handlerSet),
+      layerIdb,
+      Layer.succeed(Trace.TraceSink, mergedTraceSink),
+    );
+
+    const processManagerLayer = ProcessManager.layer({ runtimeName: Trace.CommonRuntimeName.local }).pipe(
+      Layer.provide(baseLayer),
+    );
+    const operationInvokerLayer = ProcessManager.ProcessOperationInvoker.layer.pipe(
+      Layer.provide(Layer.mergeAll(processManagerLayer, baseLayer)),
+    );
+
+    const runtimeLayer = Layer.mergeAll(baseLayer, processManagerLayer, operationInvokerLayer);
+
+    const managedRuntime = ManagedRuntime.make(runtimeLayer as Layer.Layer<any, any, never>);
+
+    // TODO(dmaretskyi): Capability modules don't currently expose a teardown
+    // hook (`makeModule` only allows `Service | Plugin.Service` in the effect's
+    // requirements, ruling out `Effect.addFinalizer`). Once the plugin
+    // framework grows a shutdown lifecycle, dispose `managedRuntime` and then
+    // call `layerStack.destroy()` to tear down keep-alive slices.
+
+    const processManagerRuntime: Capabilities.ProcessManagerRuntime = {
+      runPromise: (effect, options) => managedRuntime.runPromise(effect as Effect.Effect<any, any, any>, options),
+      runPromiseExit: (effect, options) =>
+        managedRuntime.runPromiseExit(effect as Effect.Effect<any, any, any>, options),
+      runFork: (effect, options) => managedRuntime.runFork(effect as Effect.Effect<any, any, any>, options),
+      runSync: (effect) => managedRuntime.runSync(effect as Effect.Effect<any, any, any>),
+    };
+
+    // Eagerly extract the process monitor. Safe because it does not require a
+    // fresh scope and is a stable reference for the lifetime of the runtime.
+    const processMonitor = managedRuntime.runSync(
+      Effect.flatMap(Process.ProcessMonitorService, Effect.succeed) as Effect.Effect<Process.Monitor, never, never>,
+    );
+
+    // Publish the manager into the ambient-layer holder so that
+    // `ProcessManager.ProcessManagerService` becomes resolvable through the
+    // LayerStack alongside the other framework-supplied services.
+    processManagerHolder = managedRuntime.runSync(
+      Effect.flatMap(ProcessManager.ProcessManagerService, Effect.succeed) as Effect.Effect<
+        ProcessManager.Manager,
+        never,
+        never
+      >,
+    );
+
+    // Eagerly extract the operation invoker built by ProcessOperationInvoker.layer.
+    // Pulled via the ProcessOperationInvoker tag so the contributed value carries
+    // the full OperationInvoker interface (`invocations`, `pendingFollowups`,
+    // `awaitFollowups`, `_invokeCore`) that HistoryTracker requires.
+    const operationInvoker: OperationInvoker.OperationInvoker = managedRuntime.runSync(
+      Effect.flatMap(ProcessManager.ProcessOperationInvoker.Service, Effect.succeed) as unknown as Effect.Effect<
+        OperationInvoker.OperationInvoker,
+        never,
+        never
+      >,
+    );
+
+    return [
+      Capability.contributes(Capabilities.ProcessManagerRuntime, processManagerRuntime),
+      Capability.contributes(Capabilities.ServiceResolver, serviceResolver),
+      Capability.contributes(Capabilities.ProcessMonitor, processMonitor),
+      Capability.contributes(Capabilities.OperationInvoker, operationInvoker),
+    ];
+  }),
+);

package/src/plugin-process-manager/testing.ts

@@ -0,0 +1,156 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Deferred from 'effect/Deferred';
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as Ref from 'effect/Ref';
+import * as Schema from 'effect/Schema';
+import * as Stream from 'effect/Stream';
+
+import { Operation } from '@dxos/compute';
+import { DXN } from '@dxos/keys';
+import { OperationInvoker } from '@dxos/operation';
+
+//
+// Test Operations
+//
+
+export const Compute = Operation.make({
+  input: Schema.Struct({ value: Schema.Number }),
+  output: Schema.Struct({ value: Schema.Number }),
+  meta: { key: DXN.make('org.dxos.test.compute') },
+});
+
+export const HalveCompute = Operation.make({
+  input: Schema.Struct({ value: Schema.Number }),
+  output: Schema.Struct({ value: Schema.Number }),
+  meta: { key: DXN.make('org.dxos.test.halveCompute') },
+});
+
+export const ToString = Operation.make({
+  input: Schema.Struct({ value: Schema.Number }),
+  output: Schema.Struct({ string: Schema.String }),
+  meta: { key: DXN.make('org.dxos.test.toString') },
+});
+
+export const Add = Operation.make({
+  input: Schema.Tuple(Schema.Number, Schema.Number),
+  output: Schema.Number,
+  meta: { key: DXN.make('org.dxos.test.add') },
+});
+
+export const SideEffect = Operation.make({
+  input: Schema.Void,
+  output: Schema.Void,
+  meta: { key: DXN.make('org.dxos.test.sideEffect') },
+});
+
+//
+// Test Handlers
+//
+
+export const computeHandler = Operation.withHandler(Compute, (data) =>
+  Effect.gen(function* () {
+    yield* Effect.sleep(data.value * 10);
+    return { value: data.value * 2 };
+  }),
+);
+
+export const halveComputeHandler = Operation.withHandler(HalveCompute, (data) =>
+  Effect.succeed({ value: data.value / 2 }),
+);
+
+export const toStringHandler = Operation.withHandler(ToString, (data) =>
+  Effect.succeed({ string: data.value.toString() }),
+);
+
+export const addHandler = Operation.withHandler(Add, (data) => Effect.succeed(data[0] + data[1]));
+
+export const sideEffectHandler = Operation.withHandler(SideEffect, () => Effect.succeed(undefined));
+
+//
+// Test Utilities
+//
+
+/**
+ * Event collector for testing - provides deterministic event collection using Effect primitives.
+ */
+export interface EventCollector {
+  /** All collected events. */
+  readonly events: OperationInvoker.InvocationEvent[];
+  /** Wait until N events have been collected. */
+  waitForEvents: (count: number) => Effect.Effect<void>;
+  /** Clean up the subscription fiber. */
+  dispose: Effect.Effect<void>;
+}
+
+/**
+ * Creates an event collector that subscribes to invoker events.
+ * Uses Effect primitives for synchronization.
+ */
+export const createEventCollector = (invoker: OperationInvoker.OperationInvoker): Effect.Effect<EventCollector> =>
+  Effect.gen(function* () {
+    const events: OperationInvoker.InvocationEvent[] = [];
+
+    // Ref to track current waiter (waiting for N events).
+    const waiterRef = yield* Ref.make<{ count: number; deferred: Deferred.Deferred<void> } | null>(null);
+
+    // Deferred to signal when subscription is ready.
+    const subscriptionReady = yield* Deferred.make<void>();
+
+    const checkWaiter = Effect.gen(function* () {
+      const waiter = yield* Ref.get(waiterRef);
+      if (waiter && events.length >= waiter.count) {
+        yield* Deferred.succeed(waiter.deferred, undefined);
+        yield* Ref.set(waiterRef, null);
+      }
+    });
+
+    // Fork a fiber to consume the invocation stream.
+    const fiber = yield* Effect.fork(
+      Effect.gen(function* () {
+        // Signal that subscription is about to start.
+        yield* Deferred.succeed(subscriptionReady, undefined);
+        yield* Stream.fromPubSub(invoker.invocations).pipe(
+          Stream.runForEach((event) =>
+            Effect.gen(function* () {
+              events.push(event);
+              yield* checkWaiter;
+            }),
+          ),
+        );
+      }),
+    );
+
+    // Wait for the subscription to be established.
+    yield* Deferred.await(subscriptionReady);
+    // Additional yield to ensure PubSub subscription is fully registered.
+    yield* Effect.yieldNow();
+
+    const waitForEvents = (count: number): Effect.Effect<void> =>
+      Effect.gen(function* () {
+        if (events.length >= count) {
+          return;
+        }
+        const deferred = yield* Deferred.make<void>();
+        yield* Ref.set(waiterRef, { count, deferred });
+        yield* Deferred.await(deferred);
+      });
+
+    const dispose = Fiber.interrupt(fiber);
+
+    return { events, waitForEvents, dispose };
+  });
+
+/**
+ * Waits until a condition is true, yielding to the JS event loop between checks.
+ * Uses setImmediate to allow other async work to complete.
+ */
+export const waitUntil = (condition: () => boolean): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    while (!condition()) {
+      yield* Effect.promise(() => new Promise((r) => setImmediate(r)));
+    }
+  });