@alchemy.run/effect-cluster 0.0.0-stage → 2.0.0-beta.86

package/src/internal/PoolHost.ts

@@ -0,0 +1,330 @@
+/**
+ * What every pool Layer shares, whatever runs its pool: register the
+ * entity whose Construction phase is running with the pool resource, bind
+ * what callers need onto the entity, and bundle every class the pool hosts
+ * into one Node program. A host only declares the service that runs it.
+ *
+ * @internal
+ */
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { dotAlchemyDirectory } from "alchemy/AlchemyContext";
+import * as Bundle from "alchemy/Bundle/Bundle";
+import type { Input } from "alchemy/Input";
+import * as Output from "alchemy/Output";
+import { Random } from "alchemy/Random";
+import { Self } from "alchemy/Self";
+import { Stack } from "alchemy/Stack";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Redacted from "effect/Redacted";
+import { Database, type DatabaseShape } from "../Database.ts";
+import { shardGroupKey, type Entity } from "../Entity.ts";
+import { Pool, type PoolEntity } from "../Pool.ts";
+import type { Providers } from "../Providers.ts";
+import { GATEWAY_PORT, RUNNER_PORT } from "./Gateway.ts";
+import type { HostedClass } from "./HostedRuntime.ts";
+import { HOSTED_TYPES, shortLabel, stackDnsLabel } from "./Naming.ts";
+import { PoolHost } from "./PoolHostService.ts";
+
+const VIRTUAL = "virtual:cluster-entities";
+
+/** Resolve {@link VIRTUAL} to a module that imports every class the pool hosts. */
+const entitiesPlugin = (entities: ReadonlyArray<PoolEntity>) => {
+  const source = [
+    ...entities.map(
+      (entity, i) =>
+        `import { ${entity.handler} as e${i} } from ${JSON.stringify(
+          entity.module.startsWith("file:") ? fileURLToPath(entity.module) : entity.module,
+        )};`,
+    ),
+    `export default [${entities
+      .map((entity, i) => `{ name: ${JSON.stringify(entity.name)}, value: e${i} }`)
+      .join(", ")}];`,
+  ].join("\n");
+  return [
+    {
+      name: "cluster-entities",
+      resolveId: (id: string) => (id === VIRTUAL ? `\0${VIRTUAL}` : null),
+      load: (id: string) => (id === `\0${VIRTUAL}` ? source : null),
+    },
+  ];
+};
+
+/** The pool was given a database whose network it cannot join. */
+export class DatabaseNetworkMismatch extends Data.TaggedError("Cluster.DatabaseNetworkMismatch")<{
+  readonly message: string;
+}> {}
+
+export interface PoolSettings {
+  /**
+   * The name the pool is known by. It is also the shard group the
+   * entities they host are placed in.
+   * @default ${stack}-${stage}-${id}
+   */
+  name?: string;
+  /**
+   * The shard groups an external program's entities use, which these
+   * runners serve. Entities declared with Alchemy always use the pool's
+   * own group.
+   * @default ["default"]
+   */
+  shardGroups?: string[];
+}
+
+/** What a host needs to declare the service that runs the pool. */
+export interface PoolNodes<Network, Gateway extends PoolGateway = PoolGateway> {
+  /** What the host declared for the gateway (e.g. a load balancer to register with). */
+  readonly gateway: Gateway;
+  readonly database: DatabaseShape;
+  readonly network: Network;
+  readonly pool: Pool;
+  /** The pool's name, a DNS label. */
+  readonly name: string;
+  /**
+   * The bundled program: a directory holding `runner.mjs` with a
+   * `Dockerfile`, and a hash of its
+   * contents, which changes whenever the program does.
+   */
+  readonly program: Output.Output<{
+    readonly dir: string;
+    readonly hash: string;
+  }>;
+  /** Environment every runner needs, as plain strings. */
+  readonly environment: Output.Output<Record<string, string>>;
+}
+
+/** What a host binds onto each entity so callers can reach the gateway. */
+export interface PoolGateway {
+  readonly url: Input<string>;
+}
+
+const output = <T>(value: Input<T>): Output.Output<T> =>
+  (Output.isOutput(value) ? value : Output.literal(value)) as Output.Output<T>;
+
+/** The Dockerfile every host builds the runner image from. */
+export const RUNNER_DOCKERFILE = `FROM node:26-slim
+WORKDIR /app
+COPY *.mjs /app/
+ENV NODE_ENV=production
+EXPOSE ${RUNNER_PORT} ${GATEWAY_PORT}
+ENTRYPOINT ["node", "/app/runner.mjs"]
+`;
+
+/**
+ * A pool Layer: `network` narrows the database's network to the one this
+ * host can join; `gateway` names where callers reach the pool;
+ * `nodes` declares the service that runs them.
+ */
+export const makePoolLayer = <Network, Req, Gateway extends PoolGateway = PoolGateway>(options: {
+  readonly label: string;
+  readonly id: string;
+  readonly settings: PoolSettings;
+  readonly network: (database: DatabaseShape) => Network | undefined;
+  readonly expected: string;
+  /** The longest runner name the host accepts. @default 63 */
+  readonly nameLength?: number;
+  /** The runner image's Dockerfile, when the host needs more than {@link RUNNER_DOCKERFILE}. */
+  readonly dockerfile?: string;
+  /** Where callers reach the gateway, declaring what it needs; before the pool's service. */
+  readonly gateway: (name: string, network: Network) => Effect.Effect<Gateway, never, Req>;
+  readonly nodes: (nodes: PoolNodes<Network, Gateway>) => Effect.Effect<void, never, Req>;
+}): Layer.Layer<PoolHost, never, Database | Stack | Providers | Req> =>
+  Layer.effect(
+    PoolHost,
+    Effect.gen(function* () {
+      const database = yield* Database;
+      // What was provided to the pool, like an entity's RPC middleware,
+      // goes with every class they host.
+      const services = yield* Effect.context<never>();
+      const self = Option.getOrUndefined(yield* Effect.serviceOption(Self));
+      const hostsSelf = self !== undefined && HOSTED_TYPES.has(self.Type);
+      if (globalThis.__ALCHEMY_RUNTIME__) {
+        if (hostsSelf) yield* (self as unknown as HostedClass).provideServices(services);
+        return {
+          host: (hosted) => hosted.provideServices(services),
+          deployExternal: () => Effect.void,
+        } satisfies PoolHost["Service"];
+      }
+      const network = options.network(database);
+      if (network === undefined) {
+        return yield* Effect.die(
+          new DatabaseNetworkMismatch({
+            message: `${options.label} runs runners on ${options.expected}, and its database is not on one.`,
+          }),
+        );
+      }
+      // Named up front, so an entity knows its pool without depending on
+      // the pool resource, whose bindings carry every entity's env.
+      const name = options.settings.name ?? (yield* stackDnsLabel(options.id, options.nameLength));
+      // A shard group only has to be unique within its database, and must
+      // never be one an external program uses (usually `default`). Effect
+      // Cluster stores `group:shard` in a 50-character column, so keep it short.
+      const group = `alchemy:${yield* shortLabel(options.id, 32)}`;
+      const gateway = yield* options.gateway(name, network);
+      const context = yield* Effect.context<Stack | Providers | Req>();
+
+      /** Put `hosted` on the pool, bind the gateway onto `resource`, and declare the pool. */
+      const deploy = (hosted: PoolEntity, env: Record<string, unknown>, resource: Entity) =>
+        Effect.gen(function* () {
+          const pool = yield* Pool(options.id, { name });
+          const token = yield* Random(`${options.id}GatewayToken`, {
+            bytes: 32,
+          }) as unknown as Effect.Effect<Random, never, Providers>;
+          // The hosting runners route the entity to its own shard group.
+          yield* pool.bind`${hosted.name}`({
+            entities: [hosted],
+            env:
+              hosted.program === undefined ? { ...env, [shardGroupKey(hosted.name)]: group } : env,
+          });
+          // Alchemy entities live in the pool's own shard group; an
+          // external program keeps the groups its entities use.
+          const groups =
+            hosted.program === undefined ? [group] : (options.settings.shardGroups ?? ["default"]);
+          yield* database.shardGroups.bind`${name}`({ groups });
+          // What callers need to reach the entity through the gateway.
+          yield* resource.bind`Pool`({
+            pool: group,
+            gateway: gateway.url,
+            token: token.text,
+          });
+          const stack = yield* Stack;
+          yield* options.nodes({
+            gateway,
+            database,
+            network,
+            pool,
+            name,
+            program: yield* bundleProgram(
+              options.id,
+              pool,
+              options.dockerfile ?? RUNNER_DOCKERFILE,
+            ),
+            environment: Output.all(
+              pool.env,
+              output(database.url),
+              token.text,
+              database.shardGroups.groups,
+            ).pipe(
+              Output.map(([values, url, tokenText, allGroups]) => ({
+                ...Object.fromEntries(
+                  Object.entries(values).map(([key, value]) => [key, String(value)]),
+                ),
+                ALCHEMY_STACK_NAME: stack.name,
+                ALCHEMY_STAGE: stack.stage,
+                ALCHEMY_PHASE: "runtime",
+                CLUSTER_DATABASE_URL: Redacted.value(url),
+                CLUSTER_GATEWAY_TOKEN: Redacted.value(tokenText),
+                CLUSTER_POOL: name,
+                CLUSTER_SHARD_GROUPS: groups.join(","),
+                CLUSTER_AVAILABLE_SHARD_GROUPS: allGroups.join(","),
+              })),
+            ),
+          });
+        }).pipe(Effect.provide(context));
+
+      const host = (hosted: HostedClass) =>
+        Effect.andThen(
+          hosted.provideServices(services),
+          hosted.registerPool((env) =>
+            deploy(
+              {
+                name: hosted.LogicalId,
+                module: hosted.Props.main,
+                handler: hosted.Props.handler ?? "default",
+              },
+              env,
+              hosted as unknown as Entity,
+            ),
+          ),
+        );
+
+      // The generic `Self` is the class whose phase is running. When it is
+      // not hosted on runners, the pool was given an external entity,
+      // which may be declared inside any runtime's Construction phase.
+      if (hostsSelf) yield* host(self as unknown as HostedClass);
+
+      return {
+        host,
+        deployExternal: ({ type, main, handler, program, resource }) =>
+          // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- `bind` is typed `any`; what it needs is the providers in `context`
+          deploy(
+            { name: type, module: main, handler, program },
+            {},
+            resource,
+          ) as Effect.Effect<void>,
+      } satisfies PoolHost["Service"];
+    }),
+  );
+
+const PROGRAM = "virtual:cluster-program";
+
+/** Resolve {@link PROGRAM} to the external program's bundled source, as a string. */
+const programPlugin = (source: string | undefined) => [
+  {
+    name: "cluster-program",
+    resolveId: (id: string) => (id === PROGRAM ? `\0${PROGRAM}` : null),
+    load: (id: string) =>
+      id === `\0${PROGRAM}` ? `export default ${JSON.stringify(source ?? "")};` : null,
+  },
+];
+
+/** A runner entry beside this module: `runner` (Alchemy entities) or `external-runner`. */
+const runnerEntry = (name: "runner" | "external-runner") =>
+  fileURLToPath(
+    new URL(import.meta.url.endsWith(".ts") ? `./${name}.ts` : `./${name}.js`, import.meta.url),
+  );
+
+/**
+ * Bundle the runner program and its Dockerfile into a directory of their
+ * own, once the pool knows its classes, and resolve to the directory.
+ */
+const bundleProgram = Effect.fn(function* (id: string, pool: Pool, dockerfile: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const dir = path.resolve(yield* dotAlchemyDirectory, "cluster", yield* stackDnsLabel(id));
+  return Output.mapEffect((entities: PoolEntity[]) =>
+    Effect.gen(function* () {
+      yield* fs.remove(dir, { recursive: true, force: true });
+      yield* fs.makeDirectory(dir, { recursive: true });
+      // An external program is bundled on its own and embedded in the
+      // runner, which writes it out and runs it as its own process: it reads
+      // its settings from its environment when it loads, so it can't share
+      // the runner's modules. One file, on every host.
+      const program = entities.find((entity) => entity.program !== undefined)?.program;
+      let programSource: string | undefined;
+      if (program !== undefined) {
+        const programDir = path.join(dir, "program");
+        yield* Bundle.build(
+          {
+            input: path.resolve(program),
+            platform: "node",
+            resolve: { conditionNames: [...Bundle.NODE_CONDITION_NAMES] },
+          },
+          { dir: programDir, format: "esm", entryFileNames: "program.mjs", codeSplitting: false },
+        );
+        programSource = yield* fs.readFileString(path.join(programDir, "program.mjs"));
+        yield* fs.remove(programDir, { recursive: true });
+      }
+      const runner = yield* Bundle.build(
+        {
+          input: runnerEntry(program === undefined ? "runner" : "external-runner"),
+          platform: "node",
+          resolve: { conditionNames: [...Bundle.NODE_CONDITION_NAMES] },
+          plugins: [...entitiesPlugin(entities), ...programPlugin(programSource)],
+        },
+        { dir, format: "esm", entryFileNames: "runner.mjs", codeSplitting: false },
+      );
+      const hashes = [runner.hash, dockerfile];
+      yield* fs.writeFileString(path.join(dir, "Dockerfile"), dockerfile);
+      const hash = yield* Effect.sync(() =>
+        createHash("sha256").update(hashes.join("\n")).digest("hex").slice(0, 16),
+      );
+      return { dir, hash };
+    }).pipe(Effect.orDie),
+  )(pool.entities);
+});

package/src/internal/PoolHostService.ts

@@ -0,0 +1,25 @@
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type { Entity } from "../Entity.ts";
+import type { HostedClass } from "./HostedRuntime.ts";
+
+/**
+ * What a pool Layer gives the Effect it is provided to: a way for an
+ * external `Cluster.Entity` (an existing Effect Cluster program, referenced
+ * by file) to run on the pool.
+ * @internal
+ */
+export class PoolHost extends Context.Service<
+  PoolHost,
+  {
+    /** Host a class (an entity, a workflow) on the pool: its Construction phase is running. */
+    readonly host: (self: HostedClass) => Effect.Effect<void>;
+    readonly deployExternal: (entity: {
+      readonly type: string;
+      readonly main: string;
+      readonly handler: string;
+      readonly program: string;
+      readonly resource: Entity;
+    }) => Effect.Effect<void>;
+  }
+>()("Cluster.PoolHost") {}

package/src/internal/Wire.ts

@@ -0,0 +1,83 @@
+/**
+ * What crosses between a caller and an entity's object: each call as JSON,
+ * its reply as JSON. A host's object RPC hides a thrown error's type, so
+ * failures of the object itself come back as data too.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { Rpc, RpcSchema } from "effect/rpc";
+import * as Schema from "effect/Schema";
+
+/** One call to an entity, as it crosses to the entity's object. */
+export interface Call {
+  /** The caller's id for this call: what an interrupt names. */
+  readonly requestId: string;
+  readonly tag: string;
+  readonly payload: unknown;
+  readonly headers: Record<string, string>;
+}
+
+/** A failure of the object itself, returned as data. */
+export const DEFECT = "~cluster/defect";
+
+/** A cluster error the object answered with instead of running the call. */
+export interface Rejection {
+  readonly _tag: "MailboxFull" | "AlreadyProcessingMessage" | "PersistenceError";
+  readonly message: string;
+}
+
+/**
+ * The object's answer to a call: the encoded exit of an RPC, a rejection,
+ * or the object's own defect. A stream answers with one of these per frame,
+ * plus `{ chunk }` frames before its exit.
+ */
+export type Reply =
+  | { readonly exit: unknown }
+  | { readonly rejected: Rejection }
+  | { readonly [DEFECT]: string };
+
+export type Frame = Reply | { readonly chunk: ReadonlyArray<unknown> };
+
+export const json = <S extends Schema.Top>(schema: S) =>
+  Schema.toCodecJson(schema) as unknown as Schema.Codec<unknown, unknown>;
+
+export const payloadCodec = (rpc: Rpc.AnyWithProps) => json(rpc.payloadSchema);
+export const exitCodec = (rpc: Rpc.AnyWithProps) => json(Rpc.exitSchema(rpc as Rpc.Any));
+export const chunkCodec = (rpc: Rpc.AnyWithProps) =>
+  json(RpcSchema.isStreamSchema(rpc.successSchema) ? rpc.successSchema.success : Schema.Unknown);
+
+export const encode = (codec: Schema.Codec<unknown, unknown>, value: unknown) =>
+  Schema.encodeUnknownEffect(codec)(value).pipe(Effect.orDie);
+export const decode = (codec: Schema.Codec<unknown, unknown>, value: unknown) =>
+  Schema.decodeUnknownEffect(codec)(value).pipe(Effect.orDie);
+
+/**
+ * An RPC's exit, encoded. A stream's exit carries no value. An exit its
+ * schema can't encode (a defect that isn't JSON) is sent as a defect with
+ * its message.
+ */
+export const encodeExit = (rpc: Rpc.AnyWithProps, exit: Exit.Exit<unknown, unknown>) =>
+  Schema.encodeUnknownEffect(exitCodec(rpc))(
+    RpcSchema.isStreamSchema(rpc.successSchema) ? Exit.asVoid(exit) : exit,
+  ).pipe(
+    Effect.catchCause(() =>
+      Schema.encodeUnknownEffect(exitCodec(rpc))(
+        Exit.die(Exit.isFailure(exit) ? String(exit.cause) : "unencodable exit"),
+      ),
+    ),
+    Effect.orDie,
+  );
+
+/** `(type, id)` as one object name, length-prefixed like Effect's: `7:Counter` + id. */
+export const entityObjectName = (type: string, id: string) => `${type.length}:${type}${id}`;
+
+export const parseEntityObjectName = (name: string) => {
+  const colon = name.indexOf(":");
+  const length = Number(name.slice(0, colon));
+  return {
+    type: name.slice(colon + 1, colon + 1 + length),
+    id: name.slice(colon + 1 + length),
+  };
+};

package/src/internal/WorkflowGateway.ts

@@ -0,0 +1,188 @@
+/**
+ * How callers outside the cluster reach the workflows a pool hosts: four
+ * RPCs on the pool's gateway, served by the pool's own
+ * `ClusterWorkflowEngine`, and a `WorkflowEngine` for callers that sends
+ * them. Payloads, results and signals cross as JSON, encoded with the
+ * workflow's own schemas.
+ *
+ * @internal
+ */
+import {
+  decodeExit,
+  decodeResult,
+  encodeExit,
+  encodeResult,
+  payloadCodec,
+} from "alchemy/WorkflowEncoding";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { Rpc, RpcClient, type RpcClientError, RpcGroup, RpcSerialization } from "effect/rpc";
+import * as Schema from "effect/Schema";
+import { DurableDeferred, Workflow, WorkflowEngine } from "effect/workflow";
+import { GATEWAY_PATH, type GatewayTarget, gatewayFetch } from "./Gateway.ts";
+
+const Run = { workflow: Schema.String, executionId: Schema.String };
+
+export class WorkflowRpcs extends RpcGroup.make(
+  Rpc.make("Workflow.Start", { payload: { ...Run, payload: Schema.Unknown } }),
+  Rpc.make("Workflow.Poll", {
+    payload: Run,
+    success: Schema.Struct({
+      state: Schema.Literals(["none", "suspended", "complete"]),
+      result: Schema.optional(Schema.String),
+    }),
+  }),
+  Rpc.make("Workflow.Interrupt", { payload: Run }),
+  Rpc.make("Workflow.Signal", { payload: { ...Run, name: Schema.String, exit: Schema.String } }),
+) {}
+
+class UnknownWorkflow extends Data.TaggedError("Cluster.UnknownWorkflow")<{
+  readonly workflow: string;
+}> {}
+
+/** The pool's side: each RPC on the pool's own engine, for the workflows they host. */
+export const workflowHandlers = (workflows: ReadonlyMap<string, Workflow.Any>) =>
+  WorkflowRpcs.toLayer(
+    Effect.gen(function* () {
+      const engine = yield* WorkflowEngine.WorkflowEngine;
+      const find = (name: string) => {
+        const workflow = workflows.get(name);
+        return workflow === undefined
+          ? Effect.die(new UnknownWorkflow({ workflow: name }))
+          : Effect.succeed(workflow as Workflow.Workflow<string, any, any, any>);
+      };
+      return WorkflowRpcs.of({
+        "Workflow.Start": ({ workflow: name, executionId, payload }) =>
+          Effect.gen(function* () {
+            const workflow = yield* find(name);
+            const decoded = yield* Schema.decodeUnknownEffect(payloadCodec(workflow))(payload).pipe(
+              Effect.orDie,
+            );
+            yield* engine.execute(workflow, {
+              executionId,
+              payload: decoded as object,
+              discard: true,
+            });
+          }).pipe(Effect.orDie),
+        "Workflow.Poll": ({ workflow: name, executionId }) =>
+          Effect.gen(function* () {
+            const workflow = yield* find(name);
+            const result = yield* engine.poll(workflow, executionId);
+            if (Option.isNone(result)) return { state: "none" as const };
+            if (result.value._tag === "Suspended") return { state: "suspended" as const };
+            return {
+              state: "complete" as const,
+              result: yield* encodeResult(workflow, result.value.exit),
+            };
+          }),
+        "Workflow.Interrupt": ({ workflow: name, executionId }) =>
+          Effect.flatMap(find(name), (workflow) => engine.interrupt(workflow, executionId)),
+        // The exit arrives encoded with the deferred's own schemas, so it is
+        // passed on through a deferred whose schemas leave it as it is.
+        "Workflow.Signal": ({ workflow, executionId, name, exit }) =>
+          Effect.flatMap(decodeExit(exit), (decoded) =>
+            engine.deferredDone(
+              DurableDeferred.make(name, { success: Schema.Unknown, error: Schema.Unknown }),
+              { workflowName: workflow, executionId, deferredName: name, exit: decoded },
+            ),
+          ),
+      });
+    }),
+  );
+
+/** A step only runs inside a run, and runs only run on the pool. */
+class RunsOnPool extends Data.TaggedError("Cluster.RunsOnPool")<{
+  readonly operation: string;
+}> {}
+
+const onPool = (operation: string) => Effect.die(new RunsOnPool({ operation }));
+
+/**
+ * A caller's engine: starts and reads runs through the gateway of the
+ * pool that hosts each workflow. `route` returns that gateway.
+ */
+export const makeRemoteEngine = (
+  route: (workflowName: string) => Effect.Effect<GatewayTarget>,
+): WorkflowEngine.WorkflowEngine["Service"] => {
+  const call = <A>(
+    workflowName: string,
+    use: (
+      client: RpcClient.FromGroup<typeof WorkflowRpcs, RpcClientError.RpcClientError>,
+    ) => Effect.Effect<A, unknown>,
+  ) =>
+    Effect.gen(function* () {
+      const target = yield* route(workflowName);
+      const protocol = RpcClient.layerProtocolHttp({
+        url: `${target.url.replace(/\/+$/, "")}${GATEWAY_PATH}`,
+        transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken(target.token)),
+      }).pipe(Layer.provide([FetchHttpClient.layer, RpcSerialization.layerJson]));
+      return yield* Effect.flatMap(RpcClient.make(WorkflowRpcs), use).pipe(
+        Effect.scoped,
+        Effect.provide(protocol),
+        Effect.provideService(FetchHttpClient.Fetch, yield* gatewayFetch(target.service)),
+      );
+    }).pipe(Effect.orDie);
+
+  const poll = (workflow: Workflow.Any, executionId: string) =>
+    Effect.gen(function* () {
+      const reply = yield* call(workflow._tag, (client) =>
+        client["Workflow.Poll"]({ workflow: workflow._tag, executionId }),
+      );
+      if (reply.state === "none") return Option.none<Workflow.Result<unknown, unknown>>();
+      if (reply.state === "suspended") return Option.some(Workflow.Suspended.make({}));
+      return Option.some(
+        yield* decodeResult(workflow as Workflow.AnyWithProps, reply.result ?? "null"),
+      );
+    });
+
+  return WorkflowEngine.makeUnsafe({
+    // Workflows run on their runners; nothing registers here.
+    register: () => Effect.void,
+    execute: (workflow, options) =>
+      Effect.gen(function* () {
+        const payload = yield* Schema.encodeEffect(payloadCodec(workflow as Workflow.AnyWithProps))(
+          options.payload,
+        ).pipe(Effect.orDie);
+        yield* call(workflow._tag, (client) =>
+          client["Workflow.Start"]({
+            workflow: workflow._tag,
+            executionId: options.executionId,
+            payload,
+          }),
+        );
+        if (options.discard) return undefined;
+        return Option.getOrElse(yield* poll(workflow, options.executionId), () =>
+          Workflow.Suspended.make({}),
+        );
+      }) as Effect.Effect<any>,
+    poll,
+    interrupt: (workflow, executionId) =>
+      call(workflow._tag, (client) =>
+        client["Workflow.Interrupt"]({ workflow: workflow._tag, executionId }),
+      ),
+    interruptUnsafe: (workflow, executionId) =>
+      call(workflow._tag, (client) =>
+        client["Workflow.Interrupt"]({ workflow: workflow._tag, executionId }),
+      ),
+    resume: () => Effect.void,
+    activityExecute: () => onPool("Activity execution"),
+    deferredResult: () => onPool("DurableDeferred reads"),
+    deferredDone: ({ workflowName, executionId, deferredName, exit }) =>
+      Effect.flatMap(encodeExit(exit), (text) =>
+        call(workflowName, (client) =>
+          client["Workflow.Signal"]({
+            workflow: workflowName,
+            executionId,
+            name: deferredName,
+            exit: text,
+          }),
+        ),
+      ),
+    scheduleClock: () => onPool("DurableClock scheduling"),
+  });
+};

package/src/internal/external-runner.ts

@@ -0,0 +1,10 @@
+// @ts-expect-error resolved by the pool's bundler plugin
+import entities from "virtual:cluster-entities";
+// @ts-expect-error resolved by the pool's bundler plugin
+import program from "virtual:cluster-program";
+import { runExternal } from "./Bootstrap.ts";
+
+await runExternal(
+  entities as ReadonlyArray<{ readonly name: string; readonly value: unknown }>,
+  program as string,
+);

package/src/internal/runner.ts

@@ -0,0 +1,5 @@
+// @ts-expect-error resolved by the pool's bundler plugin
+import entities from "virtual:cluster-entities";
+import { bootstrap } from "./Bootstrap.ts";
+
+await bootstrap(entities as ReadonlyArray<{ readonly name: string; readonly value: unknown }>);