@temelj/workflow 0.0.0-alpha.2 → 0.0.0-alpha.4

package/README.md

@@ -26,6 +26,10 @@
 <br/>
 <br/>
 
+<p align="center">
+🚨Alpha state; things are in high flux🚨
+</p>
+
 ## Installation
 
 ```sh
@@ -33,6 +37,394 @@
 $ npm install @temelj/workflow
 # pnpm
 $ pnpm add @temelj/workflow
-# jsr
-$ deno add jsr:@temelj/workflow # or jsr add @temelj/workflow
 ```
+
+## Overview
+
+A workflow can pause and continue after a worker restarts.
+The worker replays its event history, returning saved results for completed steps.
+Code outside those steps runs again during replay.
+
+The default client stores history in memory.
+To retain runs across restarts, configure persistent [storage](#storage).
+
+## Quick start
+
+Implement a workflow:
+
+```ts
+import { implementWorkflow } from "@temelj/workflow";
+
+export const greet = implementWorkflow<{ readonly name: string }, string>(
+  { name: "greet", version: "v1" },
+  ({ input, step }) => step.run({ name: "greeting" }, () => `Hello, ${input.name}`),
+);
+```
+
+Start a run, then have a worker execute it:
+
+```ts
+import { createWorkflowClient } from "@temelj/workflow";
+
+const client = createWorkflowClient();
+const handle = await client.runs.start(greet, { name: "Verso" });
+// Starting registers the implementation and stores a pending run.
+
+await client.workers.processRun(handle.runId); // Process this run once.
+console.log(await handle.result()); // "Hello, Verso"
+await client.close();
+```
+
+`result()` waits for completion and it doesn't run the workflow.
+
+A service can run a worker loop to claim pending runs and resume waits as they become ready:
+
+```ts
+import type { WorkflowClient } from "@temelj/workflow";
+
+export async function runWorker(client: WorkflowClient, signal: AbortSignal): Promise<void> {
+  // Register workflow implementations on this client before starting the worker.
+  try {
+    await client.workers.create().run({ concurrency: 8, signal });
+  } finally {
+    await client.close();
+  }
+}
+```
+
+Producers and workers must share the same storage.
+Each in-memory client has its own runs.
+Use a persistent backend when they run in separate processes.
+
+You can find examples in [examples/workflow](../../examples/workflow).
+
+## Writing workflows
+
+Use `step.run()` for an inline task, or declare a reusable step with `defineWorkflowStep()`:
+
+```ts
+import { defineWorkflowStep, implementWorkflow } from "@temelj/workflow";
+
+const formatGreeting = defineWorkflowStep({ name: "format-greeting" }, ({ log }, name: string) => {
+  log.info("formatting greeting", { name });
+  return `Hello, ${name}`;
+});
+
+export const reminder = implementWorkflow<{ readonly name: string }, string>(
+  { name: "reminder", version: "v1" },
+  async ({ input, step }) => {
+    const greeting = await step.call(formatGreeting, input.name);
+    await step.sleep("reminder-delay", Temporal.Duration.from({ minutes: 5 }));
+    // The worker pauses here. On replay, formatGreeting returns its saved result.
+
+    const sentAt = await step.deterministic.now("sent-at");
+    step.log.info("reminder ready", { sentAt: sentAt.toString() });
+    return greeting;
+  },
+);
+```
+
+We call this "Explicit API."
+
+You should put network calls and external writes inside steps.
+A step can run again if it fails or the worker stops before its result is saved, so make external writes idempotent.
+Use `step.deterministic` for time or random values that affect later commands.
+`step.log` suppresses repeated log lines during replay.
+
+Note, this package avoids patching globals so you shouldn't use `Math.random()` or `Date.now()` if you want deterministic runs.
+
+Workflows are versioned.
+Keep command names and their order stable for a workflow version.
+Give changed input contracts or command sequences a new version, and retain implementations needed by existing runs.
+
+### Directive syntax
+
+With the bundler plugin, directives turn ordinary async functions into workflows:
+
+```ts
+export async function createGreeting(name: string): Promise<string> {
+  "use step";
+  return `Hello, ${name}`;
+}
+
+export async function greetingWorkflow(name: string): Promise<string> {
+  "use workflow";
+  return await createGreeting(name);
+}
+
+// After the transform: await client.runs.start(greetingWorkflow, "Verso").
+```
+
+Configure the transform in your build, for example with Vite:
+
+```ts
+import { workflow } from "@temelj/workflow/vite";
+
+export default { plugins: [workflow()] };
+```
+
+We call this alternative way of declaring workflows "directive" syntax that requires a bundler, which itself produces a "compiled workflow."
+
+Adapters also exist for Rollup, Rolldown, esbuild, webpack, and Rspack.
+See the [compiled example](../../examples/workflow/basic/src/compiled-workflows.ts).
+
+Other commands use the same recorded history.
+`step.workflow.run()` waits for a child workflow.
+`step.workflow.start()` starts one without waiting for its result.
+Use `step.lock.with()` for a leased lock and `step.stream.create()` to publish chunks a reader can follow.
+`step.runData` records metadata and searchable attributes.
+The [step API](./src/types/step.ts) lists their options.
+
+## Observing runs
+
+```ts
+import { createWorkflowClient } from "@temelj/workflow";
+
+const client = createWorkflowClient();
+const unsubscribe = client.on("workflow:run-completed", ({ run }) => {
+  console.log("completed", run.id); // In-process notification.
+});
+
+const handle = await client.runs.start(greet, { name: "Verso" });
+await client.workers.processRun(handle.runId);
+console.log(await handle.status()); // "completed"
+console.log(await handle.events()); // Stored event history.
+console.log(await handle.timeline()); // Steps and waits reconstructed from that history.
+
+console.log(await client.runs.summary()); // Counts grouped by status and workflow.
+console.log(await client.runs.recoverySummary()); // Due or stale runs that may need attention.
+unsubscribe();
+await client.close();
+```
+
+For an existing run, use `await client.runs.getHandle(runId)`.
+Handles also expose `cancel()` and `streams`.
+Use `handle.streams.follow(name)` to read chunk updates until that stream closes or fails.
+Pass an abort signal to stop following early.
+
+## Messages and hooks
+
+This run pauses until an approval message arrives:
+
+```ts
+import { ss } from "@temelj/standard-schema";
+import { createWorkflowClient, defineMessageChannel, implementWorkflow } from "@temelj/workflow";
+
+const approval = defineMessageChannel({
+  name: "approval",
+  schema: ss.object({ approved: ss.boolean() }),
+});
+const review = implementWorkflow<undefined, boolean>(
+  { name: "review" },
+  async ({ step }) => (await step.message.wait(approval)).approved,
+);
+
+const client = createWorkflowClient();
+const handle = await client.runs.start(review);
+await client.workers.processRun(handle.runId);
+console.log(await handle.status()); // "waiting"
+
+// Send from an API handler or another process sharing the same storage.
+await client.messages.send(handle.runId, approval, { payload: { approved: true } });
+await client.workers.processRun(handle.runId); // Resume the waiting run.
+console.log(await handle.result()); // true
+await client.close();
+```
+
+For an external callback, create a hook and give its token to the caller:
+
+```ts
+import type { StepApi, WorkflowClient } from "@temelj/workflow";
+
+import { ss } from "@temelj/standard-schema";
+
+// Call inside a workflow handler.
+async function waitForApproval(step: StepApi): Promise<boolean> {
+  const hook = step.hook.create({
+    name: "approval",
+    schema: ss.object({ approved: ss.boolean() }),
+  });
+  await step.runData.setMetadata("callback-token", { token: hook.token });
+  // The application can read the token from the run metadata and send it to the caller.
+  return (await hook.wait()).approved;
+}
+
+// Call from the callback handler, using the token the application supplied.
+async function approve(client: WorkflowClient, token: string): Promise<void> {
+  await client.hooks.resume(token, { payload: { approved: true } });
+}
+```
+
+`step.hook.createWebhook()` adds webhook metadata to the same token-based flow.
+It doesn't create an actual HTTP endpoint.
+`parseHookToken()` decodes a token without resuming the run.
+Message payloads are validated again on replay, preserving the input to schema transforms.
+
+## Errors
+
+A retryable failure schedules another attempt according to the step's retry policy.
+
+For example, retry a rate-limited HTTP request:
+
+```ts
+import {
+  defineWorkflowStep,
+  WorkflowNonRetryableError,
+  WorkflowRetryableError,
+} from "@temelj/workflow";
+
+export const loadText = defineWorkflowStep(
+  { name: "load-text", retry: { maximumAttempts: 3 } },
+  async ({ signal }, url: string) => {
+    const response = await fetch(url, { signal }); // Attempt cancellation or timeout.
+    if (response.status === 429 || response.status >= 500) {
+      throw new WorkflowRetryableError(`HTTP ${response.status}`, {
+        retryDelay: Temporal.Duration.from({ seconds: 10 }),
+      });
+    }
+    if (!response.ok) {
+      throw new WorkflowNonRetryableError(`HTTP ${response.status}`);
+    }
+    return response.text();
+  },
+);
+```
+
+`WorkflowRetryableError` accepts `retryAt` or `retryDelay`.
+Set one, not both.
+`WorkflowNonRetryableError` fails without another attempt.
+
+Stored failures are error records.
+Match their codes with the same helper you use for live exceptions:
+
+```ts
+import { matchesWorkflowError, WorkflowErrorCode } from "@temelj/workflow";
+
+export function isInvoiceLockConflict(error: unknown): boolean {
+  return matchesWorkflowError(error, WorkflowErrorCode.LOCK_ALREADY_HELD, { key: "invoice:1" });
+}
+```
+
+Workflow errors expose `code` and optional `details`.
+Match those instead of parsing error messages.
+
+## Stored values
+
+Inputs and results use `StorageValue` from `@temelj/storage`.
+That includes JSON-like data and values such as `Date`, `Map`, and `Uint8Array`.
+Metadata and stream chunks included.
+
+Functions, cyclic objects, sparse arrays and symbols are rejected before writing.
+
+A typed workflow gives `runs.start()` a typed result.
+A run ID alone doesn't establish an output type, so validate results read through `getHandle()`:
+
+```ts
+import type { WorkflowClient } from "@temelj/workflow";
+
+import { ss } from "@temelj/standard-schema";
+
+export async function readGreeting(client: WorkflowClient, runId: string): Promise<string> {
+  const handle = await client.runs.getHandle(runId);
+  return ss.parseSync(ss.string(), await handle.result());
+}
+```
+
+Stream readers also return `StorageValue`.
+Validate chunks before using their shape.
+
+## Storage
+
+This Node.js example stores run history on disk:
+
+```ts
+import { createStorage, createSuperJsonStorageCodec } from "@temelj/storage";
+import { FileSystemStorageEngine } from "@temelj/storage/filesystem";
+import { createWorkflowClient } from "@temelj/workflow";
+
+function openClient() {
+  return createWorkflowClient({
+    storage: createStorage({
+      codec: createSuperJsonStorageCodec({ format: "bytes" }),
+      engine: new FileSystemStorageEngine({ directory: "./workflow-data" }),
+    }),
+  });
+}
+
+const first = openClient();
+const handle = await first.runs.start(greet, { name: "Verso" });
+await first.close(); // The pending run stays on disk.
+
+const second = openClient();
+second.register(greet); // Implementations live in code, not in storage.
+await second.workers.processRun(handle.runId);
+const recovered = await second.runs.getHandle(handle.runId);
+console.log(await recovered.result()); // "Hello, Verso"
+await second.close();
+```
+
+Use another [`@temelj/storage` backend](../storage/README.md) when needed.
+`@temelj/workflow/store` exposes the store contract for custom adapters.
+
+## Cloudflare Workflows
+
+@temelj/workflow workflows can run on [Cloudflare Workflows](https://www.cloudflare.com/products/workflows/).
+
+Define a host around the same `greet` implementation:
+
+```ts
+import type { CloudflareWorkflowBinding } from "@temelj/workflow/cloudflare";
+
+import { defineWorkflowBundle } from "@temelj/workflow";
+import { createCloudflareWorkflowHost } from "@temelj/workflow/cloudflare";
+
+import { greet } from "./greet.ts";
+
+interface Env {
+  readonly TEMELJ_WORKFLOW: CloudflareWorkflowBinding;
+}
+
+const host = createCloudflareWorkflowHost<Env>({ workflows: defineWorkflowBundle([greet]) });
+export class TemeljWorkflow extends host.Entrypoint {}
+
+// Call from a Worker request handler with the configured workflow binding.
+export async function startGreeting(env: Env) {
+  const runtime = host.createRuntime(env.TEMELJ_WORKFLOW);
+  return runtime.runs.start(greet, { name: "Verso" });
+}
+```
+
+Configure the Worker binding and entrypoint as shown in the [Cloudflare example](../../examples/workflow/cloudflare/).
+
+Both hosts implement `WorkflowRuntime`, so code using `runs.start()` and run handles can work with either.
+The Cloudflare runtime also has `runs.get(workflow, runId)` and `messages.send()`.
+Cloudflare manages worker execution.
+Schedules, locks, streams, and run-history inspection belong to the local client.
+
+> Note, some features from @temelj/workflow that Cloudflare doesn't support might throw an error.
+
+## OpenTelemetry
+
+Configure your OpenTelemetry SDK before creating the client:
+
+```ts
+import { createWorkflowClient } from "@temelj/workflow";
+import { createOpenTelemetryTelemetry } from "@temelj/workflow/otel";
+
+const client = createWorkflowClient({
+  telemetry: createOpenTelemetryTelemetry({
+    includeNamesInSpanNames: true, // Include workflow and step names in trace UIs.
+    includeStorageOperationSpans: false, // Omit a span for each storage operation.
+  }),
+});
+
+// Close the client when the worker stops.
+await client.close();
+```
+
+The adapter emits workflow spans and metrics through your configured providers.
+`@temelj/workflow/otel` exports the span and metric names, with attribute constants for queries.
+Pass `forceFlush` and `shutdown` callbacks if the client should also flush and close your telemetry providers.
+See the [instrumented example](../../examples/workflow/basic/src/instrumentation.ts) for SDK setup and exporter shutdown.
+
+> Note, OTEL is experimental and how telemetry data is exported isn't yet strongly defined.

package/dist/attributes.d.mts

@@ -1,15 +1,17 @@
-import { WorkflowAttributePatch, WorkflowRunAttributes } from "./types/run.mjs";
+import { AttributePatch, RunAttributes } from "./types/run.mjs";
 import { EventRecord } from "./types/events.mjs";
 //#region src/attributes.d.ts
-interface WorkflowAttributeEventPatch {
-  readonly attributes?: WorkflowRunAttributes;
+interface AttributeEventPatch {
+  readonly attributes?: RunAttributes;
   readonly removeAttributes?: readonly string[];
 }
-declare function normalizeWorkflowAttributePatch(value: WorkflowAttributePatch): WorkflowAttributePatch;
-declare function workflowAttributeEventPatch(patch: WorkflowAttributePatch): WorkflowAttributeEventPatch;
-declare function workflowAttributePatchFromEvent(event: Extract<EventRecord, {
+export declare function normalizeAttributePatch(value: AttributePatch): AttributePatch;
+export declare function workflowAttributeEventPatch(patch: AttributePatch): AttributeEventPatch;
+export declare function workflowAttributePatchFromEvent(event: Extract<EventRecord, {
   readonly kind: "attributes_set";
-}>): WorkflowAttributePatch;
-declare function applyWorkflowAttributePatch(current: WorkflowRunAttributes | undefined, patch: WorkflowAttributePatch): WorkflowRunAttributes | undefined;
+}>): AttributePatch;
+export declare function applyAttributePatch(current: RunAttributes | undefined, patch: AttributePatch): RunAttributes | undefined;
+export declare const attributeValueSchema: import("@temelj/standard-schema").Schema<unknown, string | number | boolean | null>;
+export declare const runAttributesSchema: import("@temelj/standard-schema").Schema<unknown, Record<string, string | number | boolean | null>>;
 //#endregion
-export { WorkflowAttributeEventPatch, applyWorkflowAttributePatch, normalizeWorkflowAttributePatch, workflowAttributeEventPatch, workflowAttributePatchFromEvent };
+export {};

package/dist/attributes.mjs

@@ -1,7 +1,8 @@
-import { workflowAttributePatchSchema } from "./types/run.mjs";
+import { keyedRecord, parse } from "./schema/common.mjs";
+import { ss } from "@temelj/standard-schema";
 //#region src/attributes.ts
-function normalizeWorkflowAttributePatch(value) {
-	workflowAttributePatchSchema.parse(value);
+function normalizeAttributePatch(value) {
+	parse(attributePatchSchema, value);
 	return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)));
 }
 function workflowAttributeEventPatch(patch) {
@@ -18,7 +19,7 @@ function workflowAttributePatchFromEvent(event) {
 		...Object.fromEntries((event.removeAttributes ?? []).map((key) => [key, void 0]))
 	};
 }
-function applyWorkflowAttributePatch(current, patch) {
+function applyAttributePatch(current, patch) {
 	const next = { ...current };
 	for (const [key, value] of Object.entries(patch)) if (value === void 0) delete next[key];
 	else next[key] = value;
@@ -26,5 +27,22 @@ function applyWorkflowAttributePatch(current, patch) {
 	if (entries.length === 0) return;
 	return Object.fromEntries(entries);
 }
+const WORKFLOW_ATTRIBUTE_MAX_KEY_LENGTH = 128;
+const WORKFLOW_ATTRIBUTE_MAX_COUNT = 64;
+const WORKFLOW_ATTRIBUTE_MAX_VALUE_BYTES = 1024;
+const WORKFLOW_ATTRIBUTE_RESERVED_PREFIX = "$";
+const attributeKeySchema = ss.refine(ss.refine(ss.refine(ss.string(), (key) => key.trim() !== "", "Workflow run attribute keys must not be empty"), (key) => key.length <= WORKFLOW_ATTRIBUTE_MAX_KEY_LENGTH, `Workflow run attribute key must not exceed ${WORKFLOW_ATTRIBUTE_MAX_KEY_LENGTH} characters`), (key) => !key.startsWith(WORKFLOW_ATTRIBUTE_RESERVED_PREFIX), `Workflow run attribute key uses reserved prefix ${WORKFLOW_ATTRIBUTE_RESERVED_PREFIX}`);
+const attributePrimitiveValueSchema = ss.union([
+	ss.string(),
+	ss.number(),
+	ss.boolean(),
+	ss.literal(null)
+]);
+const attributeValueSchema = ss.refine(attributePrimitiveValueSchema, (value) => encodedAttributeByteLength(value) <= WORKFLOW_ATTRIBUTE_MAX_VALUE_BYTES, `Workflow run attribute value must not exceed ${WORKFLOW_ATTRIBUTE_MAX_VALUE_BYTES} encoded bytes`);
+const runAttributesSchema = ss.refine(keyedRecord(attributeKeySchema, attributeValueSchema), (attributes) => Object.keys(attributes).length <= WORKFLOW_ATTRIBUTE_MAX_COUNT, `Workflow run attributes must not include more than ${WORKFLOW_ATTRIBUTE_MAX_COUNT} keys`);
+const attributePatchSchema = ss.refine(keyedRecord(attributeKeySchema, ss.optional(attributeValueSchema)), (attributes) => Object.keys(attributes).length <= WORKFLOW_ATTRIBUTE_MAX_COUNT, `Workflow run attributes must not include more than ${WORKFLOW_ATTRIBUTE_MAX_COUNT} keys`);
+function encodedAttributeByteLength(value) {
+	return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
 //#endregion
-export { applyWorkflowAttributePatch, normalizeWorkflowAttributePatch, workflowAttributeEventPatch, workflowAttributePatchFromEvent };
+export { applyAttributePatch, attributeValueSchema, normalizeAttributePatch, runAttributesSchema, workflowAttributeEventPatch, workflowAttributePatchFromEvent };

package/dist/bundle.d.mts

@@ -1,29 +1,11 @@
-import { Registry, WorkflowDefinitionConfig, WorkflowImplementation } from "./types/definition.mjs";
-import { Schema } from "@temelj/standard-schema";
+import { WorkflowImplementation } from "./types/definition.mjs";
+import { RegistryEntry } from "./registry.mjs";
 //#region src/bundle.d.ts
-interface WorkflowImplementationLike {
-  readonly kind: "implementation";
-  readonly definition: {
-    readonly kind: "definition";
-    readonly config: WorkflowDefinitionConfig<Schema | undefined>;
-    readonly name: string;
-    readonly version?: string;
-  };
-  readonly config: WorkflowDefinitionConfig<Schema | undefined>;
-  readonly name: string;
-  readonly version?: string;
-  readonly handler: (...args: never[]) => unknown;
-}
-/** Workflow value accepted by an immutable workflow bundle. */
-type WorkflowBundleEntry = WorkflowImplementationLike | ((...args: never[]) => unknown);
 /** Immutable collection of workflow implementations shared by workflow hosts. */
-interface WorkflowBundle {
+export interface WorkflowBundle {
   readonly kind: "workflow-bundle";
   readonly workflows: readonly WorkflowImplementation<unknown, unknown>[];
 }
 /** Defines an immutable workflow collection for local and deployed workflow hosts. */
-declare function defineWorkflowBundle(entries: readonly WorkflowBundleEntry[]): WorkflowBundle;
-/** Creates an independent mutable registry populated from a workflow bundle. */
-declare function createWorkflowBundleRegistry(bundle: WorkflowBundle): Registry;
-//#endregion
-export { WorkflowBundle, WorkflowBundleEntry, createWorkflowBundleRegistry, defineWorkflowBundle };
+export declare function defineWorkflowBundle(entries: readonly RegistryEntry[]): WorkflowBundle;
+//#endregion

package/dist/bundle.mjs

@@ -1,28 +1,12 @@
-import { WorkflowDefinitionError } from "./errors/definition.mjs";
-import "./errors/mod.mjs";
-import { getCompiledWorkflowDefinition } from "./compiled-function.mjs";
 import { Registry } from "./registry.mjs";
 //#region src/bundle.ts
 /** Defines an immutable workflow collection for local and deployed workflow hosts. */
 function defineWorkflowBundle(entries) {
-	const registry = new Registry();
-	for (const entry of entries) registry.register(workflowImplementationFromBundleEntry(entry));
+	const registry = new Registry(entries);
 	return Object.freeze({
 		kind: "workflow-bundle",
 		workflows: Object.freeze([...registry.entries()])
 	});
 }
-/** Creates an independent mutable registry populated from a workflow bundle. */
-function createWorkflowBundleRegistry(bundle) {
-	const registry = new Registry();
-	for (const workflow of bundle.workflows) registry.register(workflow);
-	return registry;
-}
-function workflowImplementationFromBundleEntry(entry) {
-	if (typeof entry !== "function") return entry;
-	const implementation = getCompiledWorkflowDefinition(entry);
-	if (implementation === void 0) WorkflowDefinitionError.compiledMetadataMissing();
-	return implementation;
-}
 //#endregion
-export { createWorkflowBundleRegistry, defineWorkflowBundle };
+export { defineWorkflowBundle };

package/dist/client/create.d.mts

@@ -1,39 +1,42 @@
 import { RegistryLike, WorkflowDefinition, WorkflowHandler, WorkflowImplementation } from "../types/definition.mjs";
+import { ObservationEventHandler, ObservationEventPattern } from "../types/observation.mjs";
 import { WorkflowBundle } from "../bundle.mjs";
 import { CreateWorkflowEngineOptions } from "../types/engine-options.mjs";
-import { WorkflowClientEngine, WorkflowWorkerEngine } from "../types/engine.mjs";
-import { WorkflowClient as WorkflowClient$1, WorkflowClientAdminApi, WorkflowClientHooksApi, WorkflowClientLocksApi, WorkflowClientMessagesApi, WorkflowClientRunsApi, WorkflowClientSchedulesApi, WorkflowClientStreamsApi, WorkflowClientWorkersApi, WorkflowRunnable } from "../types/client.mjs";
+import { WorkflowEngine } from "../engine/create.mjs";
+import { ClientAdminApi, ClientHooksApi, ClientLocksApi, ClientMessagesApi, ClientRunsApi, ClientSchedulesApi, ClientStreamsApi, ClientWorkersApi, WorkflowClient as WorkflowClient$1 } from "../types/client.mjs";
+import { Unsubscribe } from "@temelj/event";
 //#region src/client/create.d.ts
-type WorkflowClientEngineOptions = Omit<CreateWorkflowEngineOptions, "storage" | "store">;
-interface CreateWorkflowClientBaseOptions extends WorkflowClientEngineOptions {
-  readonly engine?: WorkflowClientEngine;
-  readonly workerEngine?: WorkflowWorkerEngine;
+/** Engine options, such as `storage` or `store`, plus the workflows the client starts with. */
+export interface CreateWorkflowClientOptions extends CreateWorkflowEngineOptions {
+  readonly workflows?: WorkflowBundle;
 }
-/** Options for creating a workflow client with either a registry or an immutable bundle. */
-type CreateWorkflowClientOptions = CreateWorkflowClientBaseOptions & ({
+/** Client options that share a registry with workers built over the same engine. Internal. */
+export type ClientForEngineOptions = CreateWorkflowEngineOptions & ({
   readonly registry?: RegistryLike;
   readonly workflows?: never;
 } | {
   readonly registry?: never;
   readonly workflows?: WorkflowBundle;
 });
-declare function createWorkflowClient(options?: CreateWorkflowClientOptions): WorkflowClient$1;
-/** Workflow client facade implementation. */
-declare class WorkflowClient implements WorkflowClient$1 {
+export declare function createWorkflowClient(options?: CreateWorkflowClientOptions): WorkflowClient$1;
+/** A client over an existing engine, so several clients and workers share one engine. Internal. */
+export declare function clientForEngine(engine: WorkflowEngine, options?: ClientForEngineOptions): WorkflowClient$1;
+export declare class WorkflowClient implements WorkflowClient$1 {
   #private;
-  readonly runs: WorkflowClientRunsApi;
-  readonly admin: WorkflowClientAdminApi;
-  readonly schedules: WorkflowClientSchedulesApi;
-  readonly locks: WorkflowClientLocksApi;
-  readonly hooks: WorkflowClientHooksApi;
-  readonly streams: WorkflowClientStreamsApi;
-  readonly messages: WorkflowClientMessagesApi;
-  readonly workers: WorkflowClientWorkersApi;
-  constructor(options?: CreateWorkflowClientOptions);
+  readonly runs: ClientRunsApi;
+  readonly admin: ClientAdminApi;
+  readonly schedules: ClientSchedulesApi;
+  readonly locks: ClientLocksApi;
+  readonly hooks: ClientHooksApi;
+  readonly streams: ClientStreamsApi;
+  readonly messages: ClientMessagesApi;
+  readonly workers: ClientWorkersApi;
+  constructor(options?: ClientForEngineOptions, engine?: WorkflowEngine);
+  on<Pattern extends ObservationEventPattern>(pattern: Pattern, handler: ObservationEventHandler<Pattern>): Unsubscribe;
+  once<Pattern extends ObservationEventPattern>(pattern: Pattern, handler: ObservationEventHandler<Pattern>): Unsubscribe;
+  off<Pattern extends ObservationEventPattern>(pattern: Pattern, handler: ObservationEventHandler<Pattern>): void;
   close(): Promise<void>;
   implementWorkflow<TInput, TOutput, TRawInput = TInput>(definition: WorkflowDefinition<TInput, TOutput, TRawInput>, handler: WorkflowHandler<TInput, TOutput>): WorkflowImplementation<TInput, TOutput, TRawInput>;
   register<TInput, TOutput, TRawInput = TInput>(implementation: WorkflowImplementation<TInput, TOutput, TRawInput>): void;
-  workflow<TInput, TOutput, TRawInput = TInput>(definition: WorkflowDefinition<TInput, TOutput, TRawInput>, handler: WorkflowHandler<TInput, TOutput>): WorkflowRunnable<TInput, TOutput, TRawInput>;
 }
-//#endregion
-export { CreateWorkflowClientOptions, WorkflowClient, createWorkflowClient };
+//#endregion