Skip to content

Add <WorkflowRun> and <Execution host="workflow"> to Markdown tests #547

Description

@taras

Story

As a Markdown-test author, I want a <WorkflowRun> scope containing
<Execution host="workflow">, so one test can start a workflow, interrupt it,
resume it, and inspect the state it recorded.

Example outcome

A checked-in Markdown test:

  1. creates an isolated workflow run from a fixture definition;
  2. executes it until the test ends that attempt during an observable effect;
  3. inspects the last committed journal event and Workspace state;
  4. executes the same workflow run again;
  5. proves that completed work is restored and incomplete work continues; and
  6. inspects the final status, history, output, and Workspace.

The complete scenario is readable in one document. It does not need a
TypeScript fixture to stage earlier attempts or several xmd workflow
subprocesses polling one another.

Two document-execution profiles

Form What it tests
<Execution host="run"> A document executing as ordinary xmd run, without workflow history or resumption
<WorkflowRun> with <Execution host="workflow"> One workflow identity executing, stopping, resuming, and exposing its recorded state

A real subprocess remains necessary when the claim is specifically about an
operating-system process, signal, terminal, or pipe. This issue proves workflow
lifecycle behavior rather than the mechanics of killing an xmd process.

Current gap

#454 delivered <Execution host="run">, including output and diagnostic-journal
collection through the production CLI test host.

The testing contract already reserves host="workflow" and the
<WorkflowRun> scope it requires, but no production test host implements them.
An unsupported host currently refuses the form.

As a result:

  • CLI workflow tests start, kill, resume, and poll several xmd workflow
    processes to prove behavior that belongs to the workflow run itself; and
  • workflow-package tests stage previous attempts from TypeScript because a
    Markdown test cannot create and execute a workflow run.

This issue supplies the missing workflow testing profile. Moving individual
test suites follows separately after the profile exists.

<WorkflowRun> scope

<WorkflowRun> creates an isolated workflow identity for its content. The
trusted host supplies the production workflow storage and lifecycle assembly.

Before implementation, settle the authored inputs for:

  • workflow definition;
  • pinned base revision;
  • logical run identity; and
  • any fixture state a test may specify.

The document does not supply a credential, unrestricted host path, live database
handle, or another run's storage location. Those remain host-owned.

The scope makes the run's observable records available to assertions inside the
test, including its status, history, journal, selected Workspace state, and last
committed checkpoint.

Separate <WorkflowRun> scopes cannot share an identity, storage, executor, or
temporary state accidentally.

Workflow execution

Each <Execution host="workflow"> starts or continues the workflow in its
enclosing <WorkflowRun>.

A test may perform several ordered executions against that run:

  • the first execution starts it;
  • ending an incomplete execution leaves the committed workflow state available;
  • a later execution resumes from that state; and
  • an execution after completion restores the completed result without repeating
    effects.

An interrupted attempt is represented by the execution that actually ends. A
later execution does not simulate the interruption through a flag or rewritten
fixture.

The plan must settle whether this profile is available only through xmd test
or also through the hosted-scenario runners.

Authority and lifecycle

A canonical <Test> receives a single-use authorization for every nested
execution it starts. The trusted CLI host answers the workflow profile using its
production assembly.

Public middleware may observe, refuse, and delegate the fixed request. It cannot
create a workflow run, replace its identity or inputs, or manufacture an
execution result.

Every execution, attachment, storage handle, and temporary resource belongs to
the surrounding test. Completion, failure, and cancellation stop active work
and release ownership before the test returns.

A host without the workflow testing profile refuses before creating run state
and explains that the profile is unavailable.

Acceptance

  • The CLI production test host implements <WorkflowRun> and
    <Execution host="workflow">.
  • Their authored forms make the distinction from
    <Execution host="run"> clear.
  • A checked-in Markdown test starts a workflow, ends an incomplete attempt,
    resumes it, and asserts the recorded checkpoint and final result.
  • The test can inspect workflow status, history, journal, and Workspace state.
  • Completed effects restore their results; incomplete work continues from the
    last committed state.
  • A completed workflow execution does not repeat effects when invoked again.
  • Separate workflow scopes remain isolated.
  • Public middleware and same-name components cannot create a run or falsify its
    result.
  • Cancellation stops active execution and leaves no test-owned workflow resource
    active.
  • Unsupported hosts refuse without creating storage or lifecycle state.
  • The testing specification replaces its “not built” statement with the
    completed contract.

Out of scope

  • Changing <Execution host="run">.
  • Migrating existing suites as part of the component implementation.
  • Replacing subprocess evidence for signals, terminal behavior, or process
    supervision.
  • CLI argument parsing and xmd test directory orchestration; Add in-process xmd command execution to Markdown tests #581 owns that
    testing boundary.

Related work

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions