← Home

executor-core

The one shared model of the workspace. Every other crate — executor-nu, executor-sandbox, executor-harness, wf-cli, and the executor façade — depends on this crate and surfaces failures through its error family, so a caller matches on one enum (WorkflowError) across crate boundaries.

Contents

• dsl — the typed Open Workflow Specification AST and the pipeline that turns source text into a resolved document.
• commands — native command and schema types (workspace, branch, gate, artifact).
• projection — how a loaded workflow appears outside the engine.
• error — the error family; RunId and RunStatus complete the run model.

The DSL pipeline

Source to resolved document is three stages, each with a single job:

1. Parse (dsl::parser::parse) — OWS 1.0 source in YAML or JSON (detected by the leading brace) into a RawDocument plus a Diagnostics report. Failures are typed: syntax problems as ParseError, semantic problems as ValidationError. Identifiers are constrained (letter|_ then letter|digit|_|-|.); non-fatal notes accumulate as warnings rather than aborting the parse.
2. Normalize (dsl::normalize::normalize) — Ting source shorthand (use.workflows references and <workflow>@<impl> selectors on steps) is rewritten into explicit canonical Bindings with origins (Use, Step(step-id)). After normalization no selector shorthand remains. Duplicate bindings for the same (workflow, implementation) pair from the same origin kind collapse; conflicts are left to the next stage.
3. Bind (dsl::context::resolve_bindings) — contextual <workflow>@<impl> resolution with mutual exclusion. Each workflow identity must end up bound to exactly one implementation; two distinct implementations selected for the same identity — including a step-origin binding conflicting with a use.workflows selection — is a ValidationError reporting both origins.

Native commands

commands defines the schema and value types the executor evaluates natively: workspace, branch, gate, and artifact steps. Schema and Value are shared with projection — the same schema type drives CLI argument validation and return validation.

Projection

A loaded workflow appears on three surfaces outside the engine, all derived from one declaration:

• Dynamic registration (projection::registration) — a workflow's input.schema becomes a CommandSignature: parameters, validation rules, help text. All arguments are required; unknown, missing, or mistyped arguments are rejected with a precise message; registering the same command name twice is an error.
• Return validation (projection::returns) — every workflow that returns data must declare output.schema. The run result is validated against that schema before it becomes the structured payload; mismatches (wrong type, missing field, unknown field) are rejected, never coerced or passed through.
• MCP tool projection (projection::tool) — every registered command simultaneously projects into an MCP-style agent tool wf_<name>: stable tool name, schema-derived description, JSON-Schema-style input_schema, and a binding back to the workflow. Projection collisions (two workflow names sanitizing to the same tool name) are rejected.

Run model

RunStatus is the machine-readable run lifecycle: Pending → Running → terminal Succeeded / Failed / Cancelled. RunId is the stable run identifier. The error family — ParseError, ValidationError, GateError, SandboxError, HarnessError, IoError — all convert into WorkflowError; wf-cli maps each kind to its exit code.