workflow-studio/compute

Overview

@workflow-studio/compute defines compute contracts shared by worker, adapters, and client integrations.

This package is the shared protocol layer - it provides interfaces, schemas, and branded IDs but contains no HTTP transport or error type definitions. Error types live in @workflow-studio/compute-client.

Core types

`ComputeScope`

type ComputeScope =
  | 'trigger:write'
  | 'runs:read'
  | 'runs:write'
  | 'deploy:read'
  | 'deploy:write'
  | 'world:proxy'
  | 'admin';

`Compute`

Required methods:

getDeploymentId()
publish(queueName, message, opts?)
createConsumer(queueNamePrefix, handler)

Optional methods:

trigger(req)
resume(req)
webhookIngress(provider, req)
waitUntil(effect)
getBaseUrl(port?)
start()
close()

Request/response contracts

ComputeTriggerRequest / ComputeTriggerResponse
ComputeResumeRequest / ComputeResumeResponse
ComputeWebhookResponse

Error channels

The Compute interface uses untyped (unknown) error channels. This is intentional.

Compute is a user-pluggable slot - users provide custom implementations via workflow.config.ts worker.compute factory. The two built-in implementations have fundamentally different error semantics:

createWorldComputeAdapter: wraps a World implementation using Effect.promise. Failures surface as defects, not typed errors.
Remote path via ComputeClient: produces typed ComputeClientRequestError values.

Typed error narrowing happens at the WorkflowExecutorAdapter boundary in workflow-studio (see below).

`WorkflowExecutorAdapter`

WorkflowExecutorAdapter is the internal boundary in workflow-studio where execution mode is resolved and error types are narrowed.

type WorkflowExecutorError = ComputeClientRequestError | Error;

interface WorkflowExecutorAdapter {
  mode: 'local' | 'remote';
  trigger(req): Effect<ComputeTriggerResponse, WorkflowExecutorError>;
  resume(req): Effect<ComputeResumeResponse, WorkflowExecutorError>;
  getDeploymentId(): Effect<string, WorkflowExecutorError>;
  webhookIngress?(provider, req): Effect<ComputeWebhookResponse, WorkflowExecutorError>;
}

Two built-in adapters produce this interface:

Local adapter (localExecutorAdapter): wraps user-provided handlers (which have unknown error channels) with Effect.mapError(toError), narrowing unknown to Error.
Remote adapter (remoteExecutorAdapter): uses ComputeClient methods that produce typed ComputeClientRequestError values. These pass through directly since ComputeClientRequestError is already a member of the union.

When execution.failPolicy is 'fallback-local', the remote adapter catches remote failures and falls back to local handler execution.

Compatibility adapter

createWorldComputeAdapter(world) maps world queue primitives to the compute contract:

world.getDeploymentId -> compute.getDeploymentId
world.queue -> compute.publish
world.createQueueHandler -> compute.createConsumer

This is used when compute behavior should be backed directly by a world implementation. Because it wraps world methods with Effect.promise, failures are defects (not typed errors in the Effect error channel).

On this page