Skip to main content

Version compatibility

A Workflow project's devDependencies.workflow-code must be an exact SemVer such as "0.2.7" or "0.2.7-20260826001". ^0.2.7, 0.2.x, workspace:*, local paths, and other ranges are rejected when the project loads. The exact pin records the Core used to develop and verify the project; it does not require the host to have the identical patch.

Runtime compatibility compares only major.minor. A host can run a project when those two segments match; patch and prerelease identifiers have no ordering effect. 0.2.0, 0.2.99, 0.2.4-20260826001, and 0.2.4-beta.1 all belong to the 0.2.x compatibility line, and either an older or newer host patch can run them directly. 0.1.x, 0.2.x, and 1.2.x are different lines. Any major or minor change is blocked before user modules execute, with the exact project version, actual host version, and required line in the error.

Patch releases therefore must not introduce a breaking Core API that requires a new compatibility line; such a change must increment the minor version. Dated Alpha (X.Y.Z-YYYYMMDDNNN), beta, and rc versions follow the same rule, with no date or prerelease ordering check.

Host guards​

  • Desktop pins exact Core and CLI dependencies and records the packaged versions in build-info.json. Normal runs, resume, schedules, parameter resolution, and structure inspection all validate the project against that Core version. Install a Desktop carrying the required Core major.minor line when blocked.
  • CLI pins an exact Core and constrains its peer range to that Core minor. For example, Core 0.2.7 produces >=0.2.0 <0.3.0. run, json, structure, and resolve-params validate the installed Core, the CLI's own Core pin, and the project's exact Core declaration before execution.
  • Server pins an exact Core and applies one project guard to normal, streaming, debug, parameter-resolution, resume, schedule, and other execution entries. The project's exact @workflow-code/cli pin remains a reproducible development-tool declaration and does not replace Core runtime compatibility.

Built-in projects​

In addition to minDesktopVersion, every built-in project release index must atomically declare the exact packaged components:

{
  "components": {
    "core": "0.2.7",
    "cli": "0.2.9"
  }
}

Desktop selects a release only when its minimum Desktop version is met and both its Core and CLI share the host's respective major.minor lines. After download, the exact workflow-code and @workflow-code/cli declarations in the project's package.json must match the index byte for byte. Legacy indexes remain parseable, but a new Desktop does not select a release without components, preventing an unknown runtime combination from being installed.

Desktop 0.1.22 is the first version that supports Core 0.2.x and the projectInfo.dataStorage.mode data-storage declaration. A built-in project release using Core 0.2.x must set minDesktopVersion: "0.1.22"; older Desktop versions block installation or execution instead of attempting the legacy storage API.

This table is generated from release metadata and does not require a manually maintained version matrix.

Release metadata does not yet contain an Desktop or Server record with component versions.