@mokronos/wfkit 0.1.0

package/src/errors.ts

@@ -0,0 +1,19 @@
+import { Schema } from "effect"
+
+// A typed, tagged workflow error. The returned value is both:
+//   - a class you `throw new MyError({...})` inside a step's `run`
+//   - a Schema the engine uses to (de)serialize the error across replays
+//
+// Because errors cross the durable boundary they MUST be declared this way
+// (not plain `Error`), so the engine can persist and rehydrate them.
+export const defineError = <
+  Tag extends string,
+  Fields extends Schema.Struct.Fields
+>(
+  tag: Tag,
+  fields: Fields
+) => {
+  // The self-referential generic of `Schema.TaggedErrorClass` is awkward to thread
+  // through a generic factory; the cast is purely to satisfy that phantom type.
+  return Schema.TaggedErrorClass<any>()(tag, fields) as any
+}

package/src/events.ts

@@ -0,0 +1,37 @@
+import { Context, Effect } from "effect"
+import { WorkflowEvent as WorkflowEventSchema, isWorkflowEvent } from "./schemas.ts"
+
+export { isWorkflowEvent }
+export const WorkflowEvent = WorkflowEventSchema
+export type WorkflowEvent = typeof WorkflowEventSchema.Type
+
+export type WorkflowEventSink = (event: WorkflowEvent) => void | Promise<void>
+
+export const currentWorkflowEventSink = Context.Reference<WorkflowEventSink | undefined>(
+  "wf/currentWorkflowEventSink",
+  { defaultValue: () => undefined }
+)
+
+// Durable-engine executions run on entity fibers created when the engine
+// layer is built, so they do not inherit the caller's context reference. Events that
+// carry an executionId are routed through this registry instead.
+const executionEventSinks = new Map<string, WorkflowEventSink>()
+
+export const setExecutionEventSink = (executionId: string, sink: WorkflowEventSink): void => {
+  executionEventSinks.set(executionId, sink)
+}
+
+export const removeExecutionEventSink = (executionId: string): void => {
+  executionEventSinks.delete(executionId)
+}
+
+export const emitWorkflowEvent = (event: WorkflowEvent): Effect.Effect<void> =>
+  Effect.flatMap(currentWorkflowEventSink, (fiberSink) => {
+    const executionId = (event as { readonly executionId?: string }).executionId
+    const sink = (executionId !== undefined ? executionEventSinks.get(executionId) : undefined) ?? fiberSink
+    if (sink === undefined) {
+      return Effect.void
+    }
+
+    return Effect.promise(() => Promise.resolve(sink(event)))
+  })

package/src/index.ts

@@ -0,0 +1,109 @@
+// The workflow authoring surface. An authored workflow imports ONLY from here
+// (plus pure helper functions it defines) — never `effect` or `@effect/*`.
+export { createInMemoryDeterminismState, defineStep, defineWorkflow, envSecretResolver, isSecretRef, NonDeterminismError, secret } from "./core.ts"
+export type {
+  DefinedWorkflow,
+  InMemoryDeterminismState,
+  OrchestrationCall,
+  OrchestrationKind,
+  SecretRef,
+  SecretResolver,
+  SignalOutcome,
+  Step,
+  StepConcurrency,
+  StepContext,
+  StepRetryPolicy,
+  TerminalFailure,
+  WorkflowContext,
+  WorkflowValue
+} from "./core.ts"
+export { defineError } from "./errors.ts"
+export type { WorkflowEvent, WorkflowEventSink } from "./events.ts"
+export {
+  ExecutionId,
+  JsonSchema,
+  RunEventsResponse,
+  RunsResponse,
+  WorkflowArtifact as WorkflowArtifactSchema,
+  WorkflowArtifactGraph as WorkflowArtifactGraphSchema,
+  WorkflowEvent as WorkflowEventSchema,
+  WorkflowGraph as WorkflowGraphSchema,
+  WorkflowGraphEdge as WorkflowGraphEdgeSchema,
+  WorkflowGraphNode as WorkflowGraphNodeSchema,
+  WorkflowGraphNodeMetadata as WorkflowGraphNodeMetadataSchema,
+  WorkflowGraphNodeSchemas as WorkflowGraphNodeSchemasSchema,
+  WorkflowGraphSchemas as WorkflowGraphSchemasSchema,
+  WorkflowHistoryEvent as WorkflowHistoryEventSchema,
+  WorkflowManifest,
+  WorkflowManifestEntry,
+  WorkflowRunEventRecord as WorkflowRunEventRecordSchema,
+  WorkflowRunRecord as WorkflowRunRecordSchema,
+  WorkflowRunStatus as WorkflowRunStatusSchema,
+  WorkflowsResponse,
+  decodeRunEventsResponse,
+  decodeRunsResponse,
+  decodeWorkflowsResponse,
+  decodeJsonSchema,
+  isWorkflowEvent
+} from "./schemas.ts"
+export type { JsonSchema as JsonSchemaDocument, ExecutionId as ExecutionIdValue } from "./schemas.ts"
+export { deliverSignal, SignalDeliveryError } from "./signal.ts"
+export { t } from "./schema.ts"
+export { createWorkflowRuntime, engineLayer, executeWorkflow, makeEngineLayer, makeWorkflowEffect, run, WorkflowVersionConflictError } from "./runtime.ts"
+export type { ExecuteWorkflowOptions, WorkflowRuntime, WorkflowRuntimeOptions } from "./runtime.ts"
+export type {
+  FileWorkflowStoreOptions,
+  LoadedWorkflow,
+  RunWorkflowOptions,
+  WorkflowArtifact,
+  WorkflowRunResult,
+  WorkflowSdk,
+  WorkflowSdkOptions,
+  WorkflowStore,
+  WorkflowRepository,
+  WorkflowClient,
+  WorkflowExecutionHandle,
+  WorkflowExecutionStatus,
+  WorkflowHistoryEvent,
+  WorkflowHistoryRecord,
+  WorkflowListResult,
+  PendingSignal,
+  WorkflowRunEventRecord,
+  WorkflowRunRecord,
+  WorkflowRunStatus,
+  WorkflowRunStore,
+  SqliteWorkflowRepositoryOptions,
+  WorkflowArtifactGraph,
+  WorkflowGraph,
+  WorkflowGraphEdge,
+  WorkflowGraphNode,
+  WorkflowGraphNodeSchemas,
+  WorkflowGraphNodeMetadata,
+  WorkflowGraphSchemas,
+  WorkflowGraphNodeKind,
+  WorkflowGraphOptions,
+  DiscoverIntegrationsOptions,
+  DiscoverIntegrationsResult,
+  IntegrationKind,
+  IntegrationSearchResult
+} from "./sdk/index.ts"
+export {
+  Cancelled,
+  MissingWorkflowVersionError,
+  createFileWorkflowStore,
+  createMemoryWorkflowStore,
+  createWorkflowClient,
+  createSqliteWorkflowRepository,
+  seedSqliteWorkflowRepository,
+  loadWorkflowArtifact,
+  createWorkflowSdk,
+  parseJsonText,
+  toJsonText,
+  sampleValueForJsonSchema,
+  sampleValueForSchema,
+  workflowArtifactToGraph,
+  workflowToGraph,
+  discover
+} from "./sdk/index.ts"
+export { createTestRuntime } from "./testing/index.ts"
+export type { CompensationRecorder, TestRuntime, TestRuntimeOptions } from "./testing/index.ts"

package/src/replay.ts

@@ -0,0 +1,29 @@
+import type { WorkflowHistoryEvent } from "./schemas.ts"
+
+// Events emitted from workflow-position code (as opposed to inside an
+// activity) fire again every time the durable engine replays an execution —
+// e.g. when a suspended run resumes after a signal, possibly in a fresh
+// process. History sinks use this identity to record each such event once.
+// Step, code, and compensation events are emitted inside activities or
+// finalizers, never replayed, and legitimately repeat across retry attempts,
+// so they have no dedupe identity.
+export const replayDedupeKey = (event: WorkflowHistoryEvent): string | undefined => {
+  switch (event.type) {
+    case "workflow.started":
+    case "workflow.completed":
+    case "workflow.failed":
+    case "cancellation.received":
+      return event.type
+    case "sleep.started":
+    case "sleep.completed":
+    case "signal.waiting":
+    case "signal.received":
+    case "signal.timeout":
+    case "all.started":
+    case "all.completed":
+    case "all.failed":
+      return `${event.type}:${event.activityName}`
+    default:
+      return undefined
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,314 @@
+import { mkdirSync } from "node:fs"
+import path from "node:path"
+import { NodeRuntime } from "@effect/platform-node"
+import { SqliteClient } from "@effect/sql-sqlite-bun"
+import { Effect, Exit, Layer, ManagedRuntime, Schema } from "effect"
+import { ClusterWorkflowEngine, SingleRunner } from "effect/unstable/cluster"
+import { SqlClient } from "effect/unstable/sql"
+import { DurableDeferred, WorkflowEngine } from "effect/unstable/workflow"
+import { currentSecretResolver, removeExecutionSecretResolver, setExecutionSecretResolver } from "./core.ts"
+import type { DefinedWorkflow, SecretResolver } from "./core.ts"
+import {
+  currentWorkflowEventSink,
+  emitWorkflowEvent,
+  removeExecutionEventSink,
+  setExecutionEventSink
+} from "./events.ts"
+import type { WorkflowEventSink } from "./events.ts"
+
+export interface ExecuteWorkflowOptions {
+  readonly onEvent?: WorkflowEventSink
+  readonly engineDatabasePath?: string
+}
+
+export interface WorkflowRuntimeOptions {
+  readonly backend: "memory" | "sqlite"
+  readonly databasePath?: string
+  /** Resolves SecretRef inputs to their values at step execution time.
+   *  Only the reference string is ever persisted. */
+  readonly secrets?: SecretResolver
+  readonly sqliteBusyTimeoutMs?: number
+  /** How often the engine polls storage for due timers and undelivered
+   *  messages. Durable timers (signal timeouts, long sleeps) can fire up to
+   *  one interval late. Defaults to 250ms. */
+  readonly timerPollIntervalMs?: number
+}
+
+export interface WorkflowRuntime {
+  readonly backend: "memory" | "sqlite"
+  readonly databasePath?: string
+  readonly secrets?: SecretResolver
+  register(workflows: ReadonlyArray<any>): void
+  getWorkflow(name: string, version: number): DefinedWorkflow | undefined
+  getLatestWorkflow(name: string): DefinedWorkflow | undefined
+  listWorkflows(name?: string): ReadonlyArray<DefinedWorkflow>
+  execute(options: {
+    readonly workflow: DefinedWorkflow
+    readonly payload: unknown
+    readonly executionId: string
+    readonly onEvent?: WorkflowEventSink
+  }): Promise<unknown>
+  deliverSignal(options: {
+    readonly workflow: DefinedWorkflow
+    readonly executionId: string
+    readonly deferredName: string
+    readonly payload: unknown
+    readonly onEvent?: WorkflowEventSink
+  }): Promise<void>
+  interrupt(options: {
+    readonly workflow: DefinedWorkflow
+    readonly executionId: string
+  }): Promise<void>
+  /** Wake a suspended execution so it replays to its suspension point.
+   *  No-op unless the run is recorded as suspended. */
+  resume(options: {
+    readonly workflow: DefinedWorkflow
+    readonly executionId: string
+  }): Promise<void>
+}
+
+export class WorkflowVersionConflictError extends Error {
+  readonly _tag = "WorkflowVersionConflictError"
+
+  constructor(options: { readonly name: string; readonly version: number }) {
+    super(
+      `Workflow ${options.name}@v${options.version} is already registered with different source; register a new version instead`
+    )
+    this.name = "WorkflowVersionConflictError"
+  }
+}
+
+const defaultEngineDatabasePath = () => path.join(process.cwd(), ".wf", "engine.sqlite")
+
+// All durable-execution plumbing lives here so authored workflows never touch
+// the cluster engine, the runner, or the backing store.
+export const makeEngineLayer = (options: {
+  readonly databasePath?: string
+  readonly sqliteBusyTimeoutMs?: number
+  readonly timerPollIntervalMs?: number
+} = {}) => {
+  const databasePath = path.resolve(options.databasePath ?? defaultEngineDatabasePath())
+  const sqliteBusyTimeoutMs = Math.max(0, Math.trunc(options.sqliteBusyTimeoutMs ?? 5000))
+  // The cluster default is 10 seconds, which delays every durable timer
+  // (signal timeout, long sleep) by up to that long on a single-node engine.
+  const timerPollIntervalMs = Math.max(10, Math.trunc(options.timerPollIntervalMs ?? 250))
+  mkdirSync(path.dirname(databasePath), { recursive: true })
+  const sqliteLayer = SqliteClient.layer({ filename: databasePath })
+  const configuredSqliteLayer = Layer.effectDiscard(Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient
+    yield* sql.unsafe(`PRAGMA busy_timeout = ${sqliteBusyTimeoutMs}`)
+  })).pipe(Layer.provideMerge(sqliteLayer))
+
+  return ClusterWorkflowEngine.layer.pipe(
+    Layer.provideMerge(SingleRunner.layer({
+      shardingConfig: { entityMessagePollInterval: timerPollIntervalMs }
+    })),
+    Layer.provide(configuredSqliteLayer)
+  )
+}
+
+export const engineLayer = makeEngineLayer()
+
+export const createWorkflowRuntime = (options: WorkflowRuntimeOptions): WorkflowRuntime => {
+  const workflows = new Map<string, DefinedWorkflow>()
+  const databasePath = options.databasePath
+
+  const env = () => {
+    const workflowLayers = Array.from(workflows.values()).map((workflow) => workflow.layer)
+    const base =
+      options.backend === "sqlite"
+        ? makeEngineLayer({
+            ...(databasePath === undefined ? {} : { databasePath }),
+            ...(options.sqliteBusyTimeoutMs === undefined ? {} : { sqliteBusyTimeoutMs: options.sqliteBusyTimeoutMs }),
+            ...(options.timerPollIntervalMs === undefined ? {} : { timerPollIntervalMs: options.timerPollIntervalMs })
+          })
+        : WorkflowEngine.layerMemory
+    return workflowLayers.reduce((layer, workflowLayer) => Layer.provideMerge(workflowLayer, layer), base)
+  }
+
+  // ONE engine per runtime. Building a fresh cluster node per call (execute,
+  // signal, ...) puts several SingleRunner nodes on the same store, and they
+  // fight over shard ownership — message processing becomes arbitrarily late.
+  // Rebuilt only when the registered workflow set changes.
+  let managed: { readonly signature: string; readonly runtime: ManagedRuntime.ManagedRuntime<any, unknown> } | undefined
+
+  const getManagedRuntime = () => {
+    const signature = Array.from(workflows.keys()).sort().join(",")
+    if (managed === undefined || managed.signature !== signature) {
+      if (managed !== undefined) {
+        void managed.runtime.dispose()
+      }
+      managed = { signature, runtime: ManagedRuntime.make(env()) }
+    }
+    return managed.runtime
+  }
+
+  const runEffect = <A>(effect: Effect.Effect<A, unknown, any>, onEvent?: WorkflowEventSink) =>
+    getManagedRuntime().runPromise(
+      effect.pipe(
+        Effect.provideService(currentWorkflowEventSink, onEvent),
+        Effect.provideService(currentSecretResolver, options.secrets)
+      ) as Effect.Effect<A, unknown, never>
+    )
+
+  return {
+    backend: options.backend,
+    ...(databasePath === undefined ? {} : { databasePath }),
+    ...(options.secrets === undefined ? {} : { secrets: options.secrets }),
+
+    register(registered) {
+      for (const workflow of registered) {
+        const key = `${workflow.name}@${workflow.version}`
+        const existing = workflows.get(key)
+        if (existing !== undefined && existing.sourceHash !== workflow.sourceHash) {
+          throw new WorkflowVersionConflictError({
+            name: workflow.name,
+            version: workflow.version
+          })
+        }
+        workflows.set(key, workflow)
+      }
+    },
+
+    getWorkflow(name, version) {
+      return workflows.get(`${name}@${version}`)
+    },
+
+    getLatestWorkflow(name) {
+      return Array.from(workflows.values())
+        .filter((workflow) => workflow.name === name)
+        .sort((left, right) => right.version - left.version)[0]
+    },
+
+    listWorkflows(name) {
+      return Array.from(workflows.values())
+        .filter((workflow) => name === undefined || workflow.name === name)
+        .sort((left, right) => left.name.localeCompare(right.name) || left.version - right.version)
+    },
+
+    execute({ workflow, payload, executionId, onEvent }) {
+      const workflowName = String(workflow.workflow._tag ?? workflow.engineName)
+      if (onEvent !== undefined) {
+        setExecutionEventSink(executionId, onEvent)
+      }
+      if (options.secrets !== undefined) {
+        setExecutionSecretResolver(executionId, options.secrets)
+      }
+      const effect = Effect.gen(function* () {
+        const engine = yield* WorkflowEngine.WorkflowEngine
+        yield* emitWorkflowEvent({ type: "workflow.started", workflowName, payload })
+        const result = yield* engine.execute(workflow.workflow, {
+          executionId,
+          payload: payload as any
+        }).pipe(
+          Effect.tap((result: unknown) =>
+            emitWorkflowEvent({ type: "workflow.completed", workflowName, result })
+          ),
+          Effect.tapError((error: unknown) =>
+            emitWorkflowEvent({ type: "workflow.failed", workflowName, error })
+          )
+        )
+        return result
+      })
+      return runEffect(effect, onEvent).finally(() => {
+        removeExecutionEventSink(executionId)
+        removeExecutionSecretResolver(executionId)
+      })
+    },
+
+    deliverSignal({ workflow, executionId, deferredName, payload, onEvent }) {
+      if (onEvent !== undefined) {
+        setExecutionEventSink(executionId, onEvent)
+      }
+      // The resumed replay may execute steps in THIS process (see the resume
+      // note below), so it needs the secret resolver just like execute().
+      if (options.secrets !== undefined) {
+        setExecutionSecretResolver(executionId, options.secrets)
+      }
+      const effect = Effect.gen(function* () {
+        const engine = yield* WorkflowEngine.WorkflowEngine
+        const deferred = DurableDeferred.make(deferredName, { success: Schema.Unknown })
+        yield* engine.deferredDone(deferred, {
+          workflowName: workflow.workflow._tag,
+          executionId,
+          deferredName,
+          exit: Exit.succeed(payload)
+        })
+        // deferredDone only resumes a run whose Suspended reply is already
+        // persisted. A delivery racing the suspension write would otherwise
+        // sit unnoticed until another wake-up, so nudge resume a few times
+        // (resume is a no-op unless the run is recorded as suspended).
+        for (let attempt = 0; attempt < 5; attempt++) {
+          yield* Effect.sleep("100 millis")
+          yield* engine.resume(workflow.workflow, executionId)
+        }
+      })
+      // The resumed replay may run inside THIS call's engine environment, so
+      // it needs the same event sink as the original execute to record
+      // history (compensations, cancellation, signal receipt).
+      return runEffect(effect, onEvent)
+    },
+
+    interrupt({ workflow, executionId }) {
+      const effect = Effect.gen(function* () {
+        const engine = yield* WorkflowEngine.WorkflowEngine
+        yield* engine.interrupt(workflow.workflow, executionId)
+      })
+      return runEffect(effect)
+    },
+
+    resume({ workflow, executionId }) {
+      const effect = Effect.gen(function* () {
+        const engine = yield* WorkflowEngine.WorkflowEngine
+        yield* engine.resume(workflow.workflow, executionId)
+      })
+      return runEffect(effect)
+    }
+  }
+}
+
+export const makeWorkflowEffect = (
+  wf: DefinedWorkflow,
+  payload: unknown,
+  options: ExecuteWorkflowOptions = {}
+) => {
+  const env = wf.layer.pipe(
+    Layer.provideMerge(makeEngineLayer(
+      options.engineDatabasePath === undefined ? {} : { databasePath: options.engineDatabasePath }
+    ))
+  )
+  const workflowName = String(wf.workflow._tag ?? wf.engineName ?? "Workflow")
+  const execution = Effect.gen(function* () {
+    yield* emitWorkflowEvent({ type: "workflow.started", workflowName, payload })
+    const result = yield* wf.workflow.execute(payload).pipe(
+      Effect.tap((result: unknown) =>
+        emitWorkflowEvent({ type: "workflow.completed", workflowName, result })
+      ),
+      Effect.tapError((error: unknown) =>
+        emitWorkflowEvent({ type: "workflow.failed", workflowName, error })
+      )
+    )
+    return result
+  })
+
+  return execution.pipe(
+    Effect.provide(env),
+    Effect.provideService(currentWorkflowEventSink, options.onEvent)
+  )
+}
+
+export const executeWorkflow = (
+  wf: DefinedWorkflow,
+  payload: unknown,
+  options: ExecuteWorkflowOptions = {}
+) =>
+  Effect.runPromise(
+    makeWorkflowEffect(wf, payload, options) as Effect.Effect<unknown, unknown, never>
+  )
+
+// Execute a workflow to completion as a standalone program.
+export const run = (wf: DefinedWorkflow, payload: unknown) => {
+  return (makeWorkflowEffect(wf, payload) as Effect.Effect<unknown, unknown, never>).pipe(
+    NodeRuntime.runMain
+  )
+}

package/src/schema.ts

@@ -0,0 +1,34 @@
+import { Schema } from "effect"
+
+interface SchemaVocabulary {
+  readonly string: typeof Schema.String
+  readonly number: typeof Schema.Number
+  readonly boolean: typeof Schema.Boolean
+  readonly void: typeof Schema.Void
+  readonly date: typeof Schema.Date
+  readonly struct: typeof Schema.Struct
+  readonly array: <S extends Schema.Constraint>(schema: S) => Schema.$Array<S>
+  readonly literal: typeof Schema.Literal
+  readonly taggedStruct: typeof Schema.TaggedStruct
+  readonly optional: <S extends Schema.Constraint>(schema: S) => Schema.optional<S>
+  readonly union: typeof Schema.Union
+  readonly unknown: typeof Schema.Unknown
+}
+
+// `t` is the LLM-facing schema vocabulary. We re-export a small, lowercase
+// subset of Effect's `Schema` so authored workflows never import `effect`
+// directly. Add primitives here as workflows need them — keep it small.
+export const t: SchemaVocabulary = {
+  string: Schema.String,
+  number: Schema.Number,
+  boolean: Schema.Boolean,
+  void: Schema.Void,
+  date: Schema.Date,
+  struct: Schema.Struct,
+  array: Schema.Array,
+  literal: Schema.Literal,
+  taggedStruct: Schema.TaggedStruct,
+  optional: Schema.optional,
+  union: Schema.Union,
+  unknown: Schema.Unknown
+} as const