# partial workflow (a workflow written in several files)

> A large workflow can keep its state bodies in their own files. The root `workflow W { … }` declares every state in order and writes `state S;` for a state whose body is elsewhere; a `partial workflow W { state S { … } }` in another file gives that body. The compiler puts each body back in the place of its declaration, so the split workflow is the same revision as its one-file form and a running workflow does not notice the move.

<!-- id: workflow-partial-workflow · area: workflow · stability: preview · html: https://osysharp.com/reference/workflow/partial-workflow/ -->

## Summary        {#summary}
**A workflow can be written in several files.** The root holds the whole contract — the header settings, the
events, the workflow-level handlers and slots — and lists every state in order. A state written as `state Building;`
has its body in a part: `partial workflow SliceFlow { state Building { … } }`. The compiled workflow is exactly the
one the same text gives in one file.

## Signature      {#signature}
```osy syntax
workflow <Name> {                       // the root: one per workflow
  …settings, events, on/subscribe at workflow scope…
  state <S> { … }                       // a body here
  state <T>;                            // its body is in a part
  terminal success <Done>;              // a terminal, likewise
}

partial workflow <Name> {               // a part: state bodies only
  state <T> { … }
  terminal success <Done> { }
}
```

## Description    {#description}

### The root declares every state   {#root}
The root is the ordinary `workflow` declaration. It lists every state, in the order the states have, and a state
whose body is in another file is declared with `;` in place of its body. The list is what keeps the split invisible:
a state's place in the order is part of the workflow's revision, and a reader of the root still sees every state.

### A part holds state bodies only   {#part}
A `partial workflow` repeats the workflow's name and holds `state` and `terminal` bodies — nothing else. Each body
repeats its declaration's head exactly (`terminal success Done { … }` for `terminal success Done;`). Events, header
settings, `Start`, workflow-level `on` handlers, workflow-scope `subscribe` slots and workflow-scope
`Assigned`/`Finished` stay in the root: they are the contract every state reads. A part file may hold several
bodies, under any file name. Under the [[project-layout#layout-check|layout check]] a part file holds one state and is
named after it: `SliceFlow.Building.osy` holds `partial workflow SliceFlow` with only `state Building`, as in the
example below.

### What the merge does   {#merge}
Before anything resolves, each body is put in the place of its declaration, and the parts are removed. A
workflow-scope slot reaches a state whose body is in a part exactly as it reaches one written in the root. So the
workflow's revision fingerprint, its states' order and its body names are those of the one-file form: moving a body
to a part, with no other change, deploys no new revision. An edit inside a part is an edit to the workflow and mints
a revision as any edit does. A diagnostic inside a body names the part file and its line.

A body reads names as the file it is written in sees them: a part's `using` lines reach the bodies in that part, and
the root's reach the root's. A part that names a type from another namespace writes its own `using` for it.

### Where parts may be   {#scope}
Parts merge inside one app, or inside one package. A part has its workflow's namespace. An app cannot continue a
package's workflow: a kit's workflow is extended through the slots and events the kit offers.

### The refusals   {#errors}
| Mistake | What the compiler says |
| --- | --- |
| a part with no root | ``partial workflow SliceFlow`: no `workflow SliceFlow` in this app. A workflow can be continued in another file only inside the app or package that declares it.`` — and, when a composed package declares it, ``SliceFlow is declared by package <Package>; extend a kit's workflow through its slots and events.`` |
| a body the root does not declare | ``state `Building` has a body here, but `SliceFlow` (SliceFlow.osy) declares no `state Building;`. Add it to the root's states, in the order the states should have.`` |
| a declaration no part gives a body | ``state `Building` is declared without a body, and no `partial workflow SliceFlow` gives it one.`` |
| two bodies for one state | ``state `Building` has two bodies: SliceFlow.Building.osy:3 and SliceFlow.osy:9. A state has one body.`` |
| a body with another head | ``the part must repeat the declaration's head: `terminal success Done`, not `terminal cancel Done`.`` |
| a part in another namespace | ``this part is in namespace `Osyrin.Release`, and `SliceFlow` is in `Osyrin.Planning`. A part has its workflow's namespace.`` |
| anything but a state in a part | ``a `partial workflow` holds state bodies only: `event Built` belongs in `workflow SliceFlow` (SliceFlow.osy).`` |
| two roots | ``workflow `SliceFlow` is declared twice: Again.osy:12 and SliceFlow.osy:9. A workflow has one declaration; write more of it in another file as `partial workflow SliceFlow`.`` |

## Examples       {#examples}

```osy title="SliceFlow.osy — the root" test app=workflow-partial-workflow
using Osysharp.Workflow;

enum SliceStage { Draft, Building, Done, Dropped }

entity Slice {
  [Required, MaxLength(100)] string Title;
  SliceStage Stage = SliceStage.Draft;
  int Builds;
}

workflow SliceFlow {
  Tracks = Slice.Stage;
  Initial = Draft;

  event Built(string head);
  event Approve();
  event Drop();

  subscribe Drop();                 // in every live state, Building included
  on Drop { goto Dropped; }

  state Draft {
    subscribe Built(string head);
    on Built(string head) { goto Building; }
  }
  state Building;                   // the body is in SliceFlow.Building.osy
  terminal success Done { }
  terminal cancel Dropped { }
}
```

```osy title="SliceFlow.Building.osy — a part" test app=workflow-partial-workflow
partial workflow SliceFlow {
  state Building {
    subscribe Approve();
    on Approve {
      this.Item.Builds = this.Item.Builds + 1;
      goto Done;
    }
  }
}
```

## Notes          {#notes}
- `<Wf>.Graph.SourceFile` names the root's file: the workflow is declared there.

## See also       {#see-also}
- [Workflows (the run that outlives the request)](https://osysharp.com/reference/workflow/index/) — what a workflow is, and its shape in one file
- [Version — which version of a workflow is running, and which file declares it](https://osysharp.com/reference/workflow/version/) — revisions, and why a split mints none
- [subscribe](https://osysharp.com/reference/workflow/subscribe/) — slots, including the workflow-scope ones the merge cascades
- [Extension members](https://osysharp.com/reference/entity/extension-members/) — `partial entity`, the other declaration `partial` continues
