World Composition

Overview

worker.world is the runtime world input for worker boot.

You can configure it as:

a world factory that returns a complete World, or
a composed object with base and optional queue/streams primitives.

World factory

Use this when you already have a complete world implementation.

workflow.config.ts

import { defineWorkflowStudioConfig } from 'workflow-studio';
import { createWorld } from '@workflow/world-postgres';

export default defineWorkflowStudioConfig({
  worker: {
    world: ({ env }) =>
      createWorld({
        connectionString: env.WORKFLOW_POSTGRES_URL!,
      }),
  },
});

Composed world primitives

Use this when you are composing storage, queue, and stream primitives.

workflow.config.ts

import { defineWorkflowStudioConfig } from 'workflow-studio';

type WorkerStore = {
  runs: object;
  steps: object;
  events: object;
  hooks: object;
};

function createStorageBase(_url: string): WorkerStore {
  return {
    runs: {},
    steps: {},
    events: {},
    hooks: {},
  };
}

function createQueuePrimitive(_token: string) {
  return {
    getDeploymentId: async () => 'dep_example',
    queue: async () => undefined,
    createQueueHandler: () => async () => new Response(null, { status: 202 }),
  };
}

function createStreamPrimitive(_key: string) {
  return {
    writeToStream: async () => undefined,
    closeStream: async () => undefined,
    readFromStream: async () => new Uint8Array(),
    listStreamsByRunId: async () => [],
  };
}

export default defineWorkflowStudioConfig({
  worker: {
    world: {
      base: ({ env }) => createStorageBase(env.DB_URL!),
      queue: ({ env }) => createQueuePrimitive(env.QUEUE_TOKEN!),
      streams: ({ env }) => createStreamPrimitive(env.STREAM_KEY!),
    },
  },
});

Required methods in composed mode

base must provide:

runs
steps
events
hooks

Queue methods must resolve from queue(...) or fallback from base:

getDeploymentId
queue
createQueueHandler

Stream methods must resolve from streams(...) or fallback from base:

writeToStream
closeStream
readFromStream
listStreamsByRunId

Optional pass-through methods:

writeToStreamMulti
start
close
getEncryptionKeyForRun

Factory context

World and primitive factories receive a context object with:

env for process environment variables
cwd for the current working directory

This supports provider-specific credentials and community world setup.

Failure behavior

Worker startup fails fast when:

worker.world is missing,
composed mode is missing base,
required storage/queue/stream methods are missing.

Use workflow-studio worker check-config before deployment.