> For the complete documentation index, see [llms.txt](https://engineering.umh.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://engineering.umh.app/engineering/development-process/how-to-build/coding-standards/architecture/fsmv2-workers.md).

# FSMv2 workers

The rules every FSMv2 worker in umh-core follows.

Owner: Jeremy · Discussion and work: the [FSMv2, CSE & CLI](https://linear.app/united-manufacturing-hub/project/fsmv2-cse-and-cli-4b33b007c454) project (Linear, UMH only)

FSMv2 is the second version of the finite state machine (FSM) framework in umh-core. A worker is a [control loop](/engineering/development-process/how-to-build/coding-standards/architecture/control-loops.md) in FSMv2 that keeps one part of umh-core the way the config describes it, for example a [data flow](/engineering/development-process/how-to-build/coding-standards/architecture/data-integrity.md) that reads data from one IP address.

## Rules

* New logic in umh-core is built as an [FSMv2](https://github.com/united-manufacturing-hub/united-manufacturing-hub/blob/staging/umh-core/pkg/fsmv2/README.md) worker.
* A worker is not healthy until it is proven healthy. Until a check has observed the value the worker reports, the worker is degraded or neutral. Neutral states are, for example, starting up, shutting down or idle. A simple worker without neutral states starts degraded.
* We accept that UMH shows more errors because of this rule. We keep reducing those errors, so that when something is green, the user knows it really works.
* When a child is degraded, the parent's own code has to set the parent to degraded too.
* The Management Console shows the state each worker reports. The UMH status card in the design system enforces this because it can only show a state that a worker reported.

## How a worker works

**A worker is a** [**control loop**](/engineering/development-process/how-to-build/coding-standards/architecture/control-loops.md)**.** Its desired state comes from the config, for example "the data is flowing from this IP address". The worker observes whether the data flows. If it doesn't, the worker adds a data flow.

### The supervisor

**The FSMv2 supervisor repeats this loop for every worker at a fixed interval.**

In each cycle, the supervisor collects what the worker observes. Then it asks the worker for its next state. The worker may start an action, for example starting the data flow's process.

### States

**A worker is always in one state, for example running, degraded or stopped.**

Degraded means the worker runs but has a problem that someone has to act on. Question 2 in [Error management](/engineering/development-process/how-to-build/coding-standards/architecture/error-management.md) uses this state to show an error to the person running the system.

### The worker tree

**Workers form a tree.**

The supervisor starts and stops the children that a parent lists. For example, once bridges run on FSMv2, each bridge in an umh-core instance has a connection to the machine, a read flow that reads from it and a [write flow](/engineering/development-process/how-to-build/coding-standards/architecture/data-integrity.md#an-example-process-locking) that writes to it. If the connection of a bridge is degraded, the bridge and its instance are degraded too.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://engineering.umh.app/engineering/development-process/how-to-build/coding-standards/architecture/fsmv2-workers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.