README
¶
go-workflow
go-workflow is a deterministic, embeddable workflow engine for Go. It owns
the portable graph, compiler, execution-plan, runtime state-machine, wait,
typed-value, artifact, retry, fan-out, compensation, verification, memoization,
offline, schema, and conformance contracts. A consuming host owns durable
storage, scheduling, authentication, policy, transport, UI, and the concrete
step kinds it enables.
The repository intentionally has no root Go package. Import only the packages your host needs, for example:
import (
"github.com/hollis-labs/libs/workflow/engine/compile"
"github.com/hollis-labs/libs/workflow/engine/offline"
"github.com/hollis-labs/libs/workflow/engine/stepkind"
)
Install an exact release:
go get github.com/hollis-labs/libs/workflow/engine@v0.1.0
Never resolve a workflow contract, schema, step kind, verifier, or plan by a floating "latest" version. Pin the module version and freeze exact host registries for each plan identity.
Start here
- Adoption guide — minimal embedding path, host-owned seams, conformance levels, and production checklist.
- Stability policy — pre-v1 compatibility and versioning rules.
- Changelog — release boundary, compatibility, and migration notes.
- Dependency policy — enforced core/import boundary.
- Public API snapshot — exported declaration change guard.
- Examples — graph-native source examples and their host capability assumptions.
- Architecture decisions — the extracted engine boundary and core design decisions.
runtime/inmemory and the default offline.Execute path are useful for local
embedding, examples, and contract tests. They are not durable: they do not
survive process restart and must not be used to claim production recovery.
Development gates
make check
That command verifies generation and module tidiness, then runs tests, the race detector, vet, import/public-API guards, schema goldens, and the conformance fixture manifest guard.
Copyright Hollis Labs. Licensed under the MIT License.
Documentation
¶
Overview ¶
Package workflow is the root package of the workflow module. It has no API of its own.
The workflow engine's packages (graph, compile, runtime, wait, gate and the others) sit beneath it, optional adapters are in adapters/, and the host layer (artifactfs, sqlstore) is in host/. The packages were moved in, with their history, from the separate go-workflow and go-workflow-host modules; MIGRATION.md and host/MIGRATION.md give the old and the new import paths.
The module is released with module-prefixed tags of the form workflow/vX.Y.Z.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
adapters
|
|
|
agent
Package agent implements the extraction-ready agent-session executor and the deterministic agent_launch graph composition.
|
Package agent implements the extraction-ready agent-session executor and the deterministic agent_launch graph composition. |
|
call
Package call implements the graph-native call@v1 step kind.
|
Package call implements the graph-native call@v1 step kind. |
|
call/calltest
Package calltest supplies extraction-safe call adapter conformance fixtures.
|
Package calltest supplies extraction-safe call adapter conformance fixtures. |
|
checkpoint
Package checkpoint implements checkpoint@v1 over workflow/gate declarations and the canonical workflow/wait suspension and continuation contracts.
|
Package checkpoint implements checkpoint@v1 over workflow/gate declarations and the canonical workflow/wait suspension and continuation contracts. |
|
cmd
Package cmd implements the extraction-ready cmd@v1 workflow step kind.
|
Package cmd implements the extraction-ready cmd@v1 workflow step kind. |
|
emit
Package emit implements emit@v1 as an extraction-ready, host-bound event publication step kind.
|
Package emit implements emit@v1 as an extraction-ready, host-bound event publication step kind. |
|
gate
Package gateadapter implements human_gate@v1 over the shared workflow/gate vocabulary and canonical workflow/wait continuation.
|
Package gateadapter implements human_gate@v1 over the shared workflow/gate vocabulary and canonical workflow/wait continuation. |
|
generatedapi
Package generatedapi turns bounded external API descriptions into ordinary workflow step kinds.
|
Package generatedapi turns bounded external API descriptions into ordinary workflow step kinds. |
|
generatedchild
Package generatedchild implements generated_child@v1, the extraction-safe materialization boundary for workflow definitions produced as typed values.
|
Package generatedchild implements generated_child@v1, the extraction-safe materialization boundary for workflow definitions produced as typed values. |
|
http
Package http implements the registered workflow http@v1 step kind.
|
Package http implements the registered workflow http@v1 step kind. |
|
llm
Package llm implements the provider-neutral llm@v1 workflow step kind.
|
Package llm implements the provider-neutral llm@v1 workflow step kind. |
|
mcp
Package mcp implements the workflow mcp step kind without importing an MCP protocol SDK.
|
Package mcp implements the workflow mcp step kind without importing an MCP protocol SDK. |
|
script
Package script implements the extraction-ready Goja JavaScript step kind.
|
Package script implements the extraction-ready Goja JavaScript step kind. |
|
service
Package service implements the provider-neutral service@v1 step kind.
|
Package service implements the provider-neutral service@v1 step kind. |
|
transform
Package transform implements the extraction-ready, pure expression transform step kind.
|
Package transform implements the extraction-ready, pure expression transform step kind. |
|
wait
Package waitadapter implements durable external wait step kinds over the canonical workflow/wait record and runtime continuation contract.
|
Package waitadapter implements durable external wait step kinds over the canonical workflow/wait record and runtime continuation contract. |
|
Package authoring provides immutable views over the canonical workflow graph IR for Go SDKs, UI tools, and agent-produced material.
|
Package authoring provides immutable views over the canonical workflow graph IR for Go SDKs, UI tools, and agent-produced material. |
|
Package compile owns loading, validation, import resolution, and compilation of workflow sources into executable graph plans.
|
Package compile owns loading, validation, import resolution, and compilation of workflow sources into executable graph plans. |
|
internal/planschema
Package planschema generates the committed ExecutionPlan JSON Schema from compile.ExecutionPlan while referencing graph types from the graph schema.
|
Package planschema generates the committed ExecutionPlan JSON Schema from compile.ExecutionPlan while referencing graph types from the graph schema. |
|
internal/planschema/cmd
command
|
|
|
Package conformance owns reusable black-box suites for workflow compilers, stores, runtimes, waits, step-kind registries, verification, and memoization.
|
Package conformance owns reusable black-box suites for workflow compilers, stores, runtimes, waits, step-kind registries, verification, and memoization. |
|
Package diagnostic defines application-neutral, source-mapped diagnostics for workflow authors and transports.
|
Package diagnostic defines application-neutral, source-mapped diagnostics for workflow authors and transports. |
|
Package gate defines the extraction-ready vocabulary shared by durable human gates and checkpoints.
|
Package gate defines the extraction-ready vocabulary shared by durable human gates and checkpoints. |
|
Package graph owns the application-neutral workflow graph representation, source references, source maps, and schema-bearing contracts shared by compilers, runtimes, transports, user interfaces, and conformance tests.
|
Package graph owns the application-neutral workflow graph representation, source references, source maps, and schema-bearing contracts shared by compilers, runtimes, transports, user interfaces, and conformance tests. |
|
internal/schemagen
Package schemagen generates the committed workflow graph JSON Schema from the graph package's Go types and enum declarations.
|
Package schemagen generates the committed workflow graph JSON Schema from the graph package's Go types and enum declarations. |
|
internal/schemagen/cmd
command
|
|
|
schema
Package schema exposes the committed graph IR JSON Schema as a strict, extraction-safe validation boundary for SDK, UI, and agent front ends.
|
Package schema exposes the committed graph IR JSON Schema as a strict, extraction-safe validation boundary for SDK, UI, and agent front ends. |
|
host
|
|
|
artifactfs
Package artifactfs is a crash-safe, local-filesystem implementation of go-workflow's values.ArtifactStore.
|
Package artifactfs is a crash-safe, local-filesystem implementation of go-workflow's values.ArtifactStore. |
|
sqlstore
Package sqlstore is a SQLite-backed implementation of go-workflow's runtime.StateStore and every companion runtime store interface (waits, memoization, recovery, compensation, scheduler resources, and the rest; see assertions.go for the full list).
|
Package sqlstore is a SQLite-backed implementation of go-workflow's runtime.StateStore and every companion runtime store interface (waits, memoization, recovery, compensation, scheduler resources, and the rest; see assertions.go for the full list). |
|
internal
|
|
|
importguard
Package importguard verifies the standalone module's dependency and public API boundaries during tests.
|
Package importguard verifies the standalone module's dependency and public API boundaries during tests. |
|
Package offline defines extraction-ready build manifests and an embedded workflow runner for the conservative daemon-less execution subset.
|
Package offline defines extraction-ready build manifests and an embedded workflow runner for the conservative daemon-less execution subset. |
|
Package runtime owns application-neutral workflow execution mechanics, including node lifecycle state, readiness, retries, cancellation, and replay.
|
Package runtime owns application-neutral workflow execution mechanics, including node lifecycle state, readiness, retries, cancellation, and replay. |
|
inmemory
Package inmemory provides the public concurrency-safe, process-lifetime implementation of the workflow runtime storage contracts.
|
Package inmemory provides the public concurrency-safe, process-lifetime implementation of the workflow runtime storage contracts. |
|
runtimetest
Package runtimetest preserves the original test-support import path for the public process-lifetime in-memory runtime store.
|
Package runtimetest preserves the original test-support import path for the public process-lifetime in-memory runtime store. |
|
Package stepkind owns application-neutral step-kind metadata, registry, and executor contracts.
|
Package stepkind owns application-neutral step-kind metadata, registry, and executor contracts. |
|
stepkindtest
Package stepkindtest provides application-neutral fake step kinds for compiler, runtime, and conformance tests.
|
Package stepkindtest provides application-neutral fake step kinds for compiler, runtime, and conformance tests. |
|
Package values owns the typed workflow data plane: JSON-compatible inline values, opaque artifact references, producer and classification metadata, deterministic digests, and value-set references.
|
Package values owns the typed workflow data plane: JSON-compatible inline values, opaque artifact references, producer and classification metadata, deterministic digests, and value-set references. |
|
Package verification defines application-neutral post-execution checks, literal activity evidence, verifier registration, and durable reports.
|
Package verification defines application-neutral post-execution checks, literal activity evidence, verifier registration, and durable reports. |
|
Package wait defines application-neutral durable wait, resume, and timed activation contracts.
|
Package wait defines application-neutral durable wait, resume, and timed activation contracts. |
Click to show internal directories.
Click to hide internal directories.