🚀 Start and resume a workflow run from the CLI (#366 PR 2)

.github/workflows/publish-packages.yml

@@ -30,7 +30,7 @@ jobs:
       - name: Validate the manifests declare this version
         run: |
           VERSION="${{ steps.resolve.outputs.value }}"
-          for f in packages/durable-streams/deno.json packages/runtime/deno.json packages/core/deno.json packages/acp/deno.json packages/testing/deno.json packages/test-agent/deno.json packages/web/deno.json packages/cli/deno.json packages/code-review-agent/deno.json packages/workflow/deno.json; do
+          for f in packages/durable-streams/deno.json packages/runtime/deno.json packages/core/deno.json packages/acp/deno.json packages/testing/deno.json packages/test-agent/deno.json packages/web/deno.json packages/workflow/deno.json packages/cli/deno.json packages/code-review-agent/deno.json; do
             declared="$(jq -r .version "$f")"
             if [ "$declared" != "$VERSION" ]; then
               echo "::error::$f declares $declared, not $VERSION — the tag does not match the manifests"
@@ -110,8 +110,15 @@ jobs:
       package: packages/web
       version: ${{ needs.version.outputs.value }}
 
+  workflow:
+    needs: [version, core, durable-streams, runtime]
+    uses: ./.github/workflows/publish-one.yml
+    with:
+      package: packages/workflow
+      version: ${{ needs.version.outputs.value }}
+
   cli:
-    needs: [version, acp, core, durable-streams, runtime, test-agent, testing, web]
+    needs: [version, acp, core, durable-streams, runtime, test-agent, testing, web, workflow]
     uses: ./.github/workflows/publish-one.yml
     with:
       package: packages/cli
@@ -124,13 +131,6 @@ jobs:
       package: packages/code-review-agent
       version: ${{ needs.version.outputs.value }}
 
-  workflow:
-    needs: [version, core, durable-streams, runtime]
-    uses: ./.github/workflows/publish-one.yml
-    with:
-      package: packages/workflow
-      version: ${{ needs.version.outputs.value }}
-
   jsr:
     needs: [version]
     runs-on: ubuntu-latest

README.md

@@ -113,6 +113,95 @@ Useful flags:
 - `--verbose`, `-V` - print durable journal entries to stderr while running.
 - `--component-dir` - add component search directories. Defaults to `components` and `.`.
 
+## Run a document as a workflow
+
+`xmd run` executes against your own filesystem and promises nothing afterwards.
+`xmd workflow` executes against a **run**: one retained Workspace and one
+journal, in a database that outlives the process, so an interrupted procedure
+continues from where it stopped rather than from the beginning.
+
+```bash
+xmd workflow start flows/prepare-release.md
+xmd workflow start --id=release-1.4 --props-channel=stable flows/prepare-release.md
+xmd workflow resume release-1.4
+```
+
+`start` names a document; `resume` names a run. A document path locates a
+definition and never selects a previous run, so starting the same document twice
+makes two runs. `resume` takes no document and no properties: it uses the ones
+its run retained.
+
+What the run executes is the **committed** document. `start` resolves `HEAD`
+once and stores that commit as the run's identity, so uncommitted edits in your
+working tree do not change what a run is a run of, and a resume months later
+loads the same object rather than whatever the file says now.
+
+Inside a run, `<File>` and `<Glob>` name entries in the run's own logical
+filesystem rather than yours. Each read, write and search is one durable effect:
+the change, the Workspace version it produces and the journal entry commit
+together, so a crash leaves all three or none, and a resume restores what
+already happened instead of doing it again. Operations a run does not have —
+a temporary directory, a native service — fail explicitly rather than reaching
+your machine.
+
+Identity and outcome go to standard error, so piping stdout still gives you the
+document:
+
+```text
+workflow run: release-1.4
+workflow status: completed
+```
+
+Only a completed run exits `0`. Failed exits `1`, suspended `2`, cancelled `3`
+and interrupted `130`, so a script cannot mistake an incomplete workflow for a
+finished one.
+
+Runs live under `~/.xmd/runs`; set `XMD_WORKFLOW_RUNS` to an absolute path to
+keep them somewhere else. The command is available through the Deno entrypoint
+and the compiled binary; under Node and Bun it reports that and does nothing.
+
+Status, list, history, cancel and fork are designed but not yet shipped.
+
+## Run a workflow
+
+`xmd run` executes against the directory you are in and promises nothing
+afterwards. `xmd workflow` executes against a *run*: one retained Workspace and
+one filtered journal, in a database that outlives the process, so an interrupted
+procedure resumes from where it stopped instead of starting again.
+
+```bash
+xmd workflow start flows/prepare-release.md
+xmd workflow start --id=release-1.4 --props-channel=stable flows/prepare-release.md
+xmd workflow resume release-1.4
+```
+
+`start` names a document; `resume` names a run. A document path locates a
+definition and never selects a previous run, so starting the same document twice
+without `--id` creates two runs. Reusing an `--id` addresses the same run when
+the definition, base and normalized properties all agree, and is refused when
+any of them differ.
+
+What a run is, is a Git object: the repository containing the document, the
+commit `HEAD` resolves to, and the document's path inside it. **The committed
+document runs**, so uncommitted edits in your working tree do not change what a
+run is a run of, and a resume months later means the same thing it did.
+
+Inside a run, `<File>` and `<Glob>` name entries in the run's own logical
+filesystem rather than yours. Each read, write and search is one durable effect:
+the mutation, the Workspace root it produces and the journal result commit
+together, and a resume restores what was recorded instead of doing it again.
+Operations a run does not have — a temporary directory, a native service — fail
+explicitly rather than reaching your machine.
+
+Runs live under `~/.xmd/runs`; set `XMD_WORKFLOW_RUNS` to an absolute directory
+to keep them somewhere else. Only a completed run exits `0` — failed exits `1`,
+suspended `2`, cancelled `3` and interrupted `130` — and the run id and final
+status are written to standard error as `workflow run: <id>` and
+`workflow status: <status>`, so standard output stays the document's own.
+
+`xmd workflow` is available through the Deno entrypoint and the compiled binary.
+Under Node and Bun the command exists and refuses before creating anything.
+
 ## Coding agents
 
 Run ACP-compatible coding agents directly from a document with `<Agent>`,