system-formalisms
The formalisms an aspect of a system can be made in — each declared as data, in a folder of its own with its analyses. Headless: data and pure functions. Published as @wity-ai/system-formalisms; in the monorepo, wity-system/formalisms.
What an aspect and a formalism are, and how a system holds them: Aspects and formalisms.
import { formalisms, process, stateMachine, petriNet, behaviourTree, syntaxTree, describe, describeInWords, lanes, STEP_KINDS } from 'wity-system/formalisms';| Export | What it is |
|---|---|
formalisms | every formalism of the package, as an array — what to hand a system: new SystemGraph({ GraphAbstract, formalisms }) |
process, stateMachine, petriNet, behaviourTree, syntaxTree | each formalism's declaration |
STEP_KINDS | the kinds of step of a process, each with its label, what it is, and the flows it takes in and out |
lanes(aspect) | a process's own analysis: { lanes: [{ performedBy, steps }], handovers: [{ from, to, fromPerformer, toPerformer, label? }] } |
describe(declaration) | a formalism as plain data for a guide or a help text: { id, label, when?, not?, member, line, kinds, anyKind, memberTypeKind?, lineKinds, links, rules, analyses } |
describeInWords(declaration) | the same as one paragraph |
describe reads only the declaration, so whatever is said with it — a command's help, a guide, this page — is what the code checks.
The formalisms
Generated from the declarations (node docs/generate.mjs).
Process — formalism process
Use it for: Things that happen in an order — a procedure, a workflow, a flowchart, a checklist with decisions in it.
Not for: Parts that exist and connect (that is the map's assets and connections), or how a number changes over time (a behaviour).
Its members are called steps, its lines flows.
| Kind of step | What it is | flows in | flows out |
|---|---|---|---|
start | where the process begins | 0 | 1 |
end | where it finishes | 1 or more | 0 |
task | a piece of work | 1 or more | 1 |
branch | one way out is taken — each flow out says its case in its label | 1 or more | 2 or more |
split | every way out is taken, side by side | 1 or more | 2 or more |
join | waits for all the ways in, then goes on | 2 or more | 1 |
| Kind of flow | What it says |
|---|---|
then | from happens, then to |
A step may name: performedBy — the uid of the asset that does the step — the steps one asset does are its lane.
A member type of this formalism is a task unless it says another kind.
Checked (beside the lines in and out above):
- A process begins at one start
- A process finishes at an end
- Each way out of a branch says the case it is taken in, and no two say the same
- A step is performed by an asset of the system
- Every step can be reached from the start
- From every step, an end can be reached
Its own analyses: lanes — who performs which steps, and where the work changes hands.
State machine — formalism state-machine
Use it for: The conditions one thing can be in and the events that move it between them — an order (placed, paid, shipped), a connection, a door, a document under review.
Not for: Work done in an order by several parts (that is a process), or a choice someone must make (a decision).
Its members are called states, its lines transitions.
| Kind of state | What it is | transitions in | transitions out |
|---|---|---|---|
initial | where it starts — a marker, with one transition to the first state | 0 | 1 |
state | a condition it stays in until an event takes it elsewhere | any | any |
final | where it ends — nothing leaves it | any | 0 |
| Kind of transition | What it says |
|---|---|
transition | on the event in label, from gives way to to (guard: a condition that must also hold) |
A member type of this formalism is a state unless it says another kind.
Checked (beside the lines in and out above):
- A state machine starts at one initial marker
- Each transition out of a state says the event it is taken on, and no two out of one state say the same
- Every state can be reached from the initial marker
Petri net — formalism petri-net
Use it for: Things that are used up and made, or shared and waited for — stock and orders, machines and jobs, a protocol where two sides must both be ready.
Not for: A plain order of steps with no counting of what is available (that is a process).
Its members are called nodes, its lines arcs.
| Kind of node | What it is | arcs in | arcs out |
|---|---|---|---|
place | holds tokens — a stock, a free machine, a waiting order (tokens: how many it starts with) | any | any |
transition | something that happens when every place leading into it has enough tokens | any | any |
| Kind of arc | What it says |
|---|---|
arc | from a place to a transition (it takes tokens) or from a transition to a place (it gives them); weight: how many — only place → transition, transition → place |
A member type of this formalism is a place unless it says another kind.
Checked (beside the lines in and out above):
- A Petri net has at least one place
- A Petri net has at least one transition
- Each arc joins the kinds it may: arc place → transition or transition → place
- No node is cut off from the rest
Behaviour tree — formalism behaviour-tree
Use it for: How an agent — a robot, a game character, an automated responder — picks what to do next from what is true right now: priorities, fallbacks, checks before acting.
Not for: A fixed order of steps (that is a process), or the conditions a thing can be in (a state machine).
Its members are called nodes, its lines links.
| Kind of node | What it is | links in | links out |
|---|---|---|---|
sequence | does its children in order; fails at the first that fails | 0 to 1 | 1 or more |
selector | tries its children in order; succeeds at the first that succeeds | 0 to 1 | 1 or more |
parallel | does all its children; succeeds when all succeed | 0 to 1 | 1 or more |
inverter | one child; succeeds when it fails and fails when it succeeds | 0 to 1 | 1 |
repeat | one child, done again (times: how many; forever when not said) | 0 to 1 | 1 |
action | a leaf: something done | 0 to 1 | 0 |
condition | a leaf: something checked — true or false | 0 to 1 | 0 |
| Kind of link | What it says |
|---|---|
child | to is a child of from; a node's children are tried in the order of its lines |
A member type of this formalism is a action unless it says another kind.
Checked (beside the lines in and out above):
- It is a tree: each node has at most one parent, and none leads back to itself
- It is one tree: no node is cut off from the rest
Syntax tree — formalism syntax-tree
Use it for: The structure of something written — a formula, a line of code, a query, a sentence — shown as parts within parts.
Not for: Choosing what to do (a behaviour tree), or steps in an order (a process).
Its members are called nodes, its lines links.
A node is of any kind you name.
| Kind of link | What it says |
|---|---|
child | to is a part of from; parts are in the order of the lines, and label may say what part it is |
Checked (beside the lines in and out above):
- It is a tree: each node has at most one parent, and none leads back to itself
- It is one tree: no node is cut off from the rest