FE-1887: Add a compiler from Flow Definitions to Petri nets by CiaranMn · Pull Request #10097 · hashintel/hash

CiaranMn · 2026-10-19T16:59:27Z

🌟 Purpose

We want to use Petri net (PN) representations for Flows in two places:

In the frontend, for editing purposes (although we will also be introducing a visual abstraction on top of Petri nets to make editing easier, while also offering the ability to see the underlying Petri net – FE-1912)
In the executor itself, which will use the PN representation and PN semantics to decide when to execute steps, route outputs/inputs, etc (FE-1904)

The PN representation will not be stored in the database. We will keep using the more minimal Flow Definition format. This gives us the freedom to change how we compile to a PN, for example to change how we compose sub-nets.

This PR adds the compiler: a new package, @local/flow-petri-net, that turns a FlowDefinition into a Petrinaut-format net. The alternative to using a new package would be the existing @local/hash-isomorphic-utils, but making that dependent on @hashintel/petrinaut-core (as the compiler requires) would cause a change to petrinaut-core to invalidate the build of many other packages. We can always revisit this.

Nothing in the app calls the compiler yet. FE-1897 (next) will use it to show a flow as its net in the flow and run pages, and FE-1904 to run them.

This is an initial version – we'll definitely need to change it when we update how subnet composition works in Petrinaut (moving to place fusion), and there are probably lots of improvements that can be made beyond those noted in known issues.

🔍 Changes

Where	What it does
`libs/@local/flow-petri-net/README.md`	What a compiled net looks like, with diagrams, and its limitations.
`src/compile-flow-definition.ts`	`compileFlowDefinition`, the package's one export: indexes the steps, adds the root net's places and `runStart`, compiles each step, and generates the subnets the steps use.
`src/compile-flow-definition/generate-action-subnet.ts`	The subnet each action's steps are instances of: a port for each input and output, and the lifecycle of running the action, with retries.
`src/compile-flow-definition/compile-action-step.ts`, `compile-for-each-step.ts`	Each kind of step: an action step's instance and its `route` and `fail` transitions, and a `for-each` step's iterator and accumulator.
`src/compile-flow-definition/shared/value-places.ts`	Where each flow input and step output is held, and the `copy` transitions where one token has to become several.
`src/compile-flow-definition/shared/` (the rest)	The step index, the net being built, ids, token colours, the generated kernels, layout, and helpers for making places, transitions and arcs.

What the executor and a run's view need from the net

Roles. Each transition has a metadata.role. The executor (FE-1904) fires succeedAttempt and failAttempt when an action's activity completes, and every other transition as soon as it's enabled. Each role is named for what its transition does, verb first, so that no two kinds of transition share one.
Steps. Every transition added for a step names it in metadata.stepId, so a run's view (FE-1932) can map between steps and the net.
Ids. The compiler builds the net from readable keys, such as p.input.prompt or t.route.<step>. Since FE-1882, Petrinaut converts any id that isn't a UUID to a UUIDv5 when it loads a net. Each id in a compiled net is already that UUID, made from its key with toPetrinautId.

⚠️ Known issues

A compiled net doesn't simulate meaningfully. The generated kernels only carry run_id and item_path forward, and there are no guards: nothing correlates tokens of one run, or stops the iterator and accumulator. The executor interprets transitions by their role instead (FE-1904).
Skipping isn't represented yet. An optional input with nothing connected, and no default, gets a token marked absent (present: false). But a step whose value on a "skip when missing" connection is absent isn't skipped in the net, and an optional output the action didn't produce isn't marked absent: both need the executor's absent tokens (FE-1904).
A for-each step's item tokens stay after their item finishes. t.startItem puts one token per item in the step's item place, and the steps inside the for-each read it, so each of them can see the item. Nothing consumes it. Consuming it needs a transition that knows every step of that item has finished, which needs the item correlation that FE-1914 adds.
Petrinaut's Actual Mode can't show a run on the net yet. It only reads the places of the root net, and a step's outputs usually stay in its instance's ports. FE-1932 shows a run on its net, and covers places inside instances.
An action with no outputs leaves its done token in its port. No action has no outputs today, so this case isn't tested.

vercel · 2026-10-19T16:59:34Z

The latest updates on your projects. Learn more about Vercel for GitHub.

4 Skipped Deployments

Project	Deployment	Actions	Updated
hash	Ignored	Preview	Oct 20, 2026 12:58pm UTC
hashdotdesign-tokens	Ignored	Preview	Oct 20, 2026 12:58pm UTC
petrinaut	Skipped		Oct 20, 2026 12:58pm UTC
petrinaut-docs	Skipped		Oct 20, 2026 12:58pm UTC

Copilot

🟡 Changes recommended

Valid definitions can produce identifier collisions, rejected kernels, blocked item consumers, and ambiguous input routing.

4 open issues

What changed in this PR

Adds @local/flow-petri-net to compile Flow Definitions into Petrinaut nets for future visualization and execution, while keeping definitions as the source of truth.

Changes:

Compiles action lifecycles, for-each steps, and value routing.
Adds deterministic IDs, token colours, metadata, kernels, and layout.
Includes compatibility tests, documentation, and package setup.

File	Description
`yarn.lock`	Registers the workspace package.
`libs/@local/flow-petri-net/turbo.json`	Configures build and test dependencies.
`libs/@local/flow-petri-net/tsconfig.json`	Configures TypeScript checking.
`libs/@local/flow-petri-net/tsconfig.build.json`	Configures build output.
`libs/@local/flow-petri-net/src/compile-flow-definition/shared/value-places.ts`	Allocates value storage and consumer copies.
`libs/@local/flow-petri-net/src/compile-flow-definition/shared/step-places.ts`	Defines lifecycle place IDs.
`libs/@local/flow-petri-net/src/compile-flow-definition/shared/net-elements.ts`	Defines transition roles and element helpers.
`libs/@local/flow-petri-net/src/compile-flow-definition/shared/net-builder.ts`	Accumulates root-net elements.
`libs/@local/flow-petri-net/src/compile-flow-definition/shared/lay-out.ts`	Positions net nodes.
`libs/@local/flow-petri-net/src/compile-flow-definition/shared/kernels.ts`	Generates placeholder token kernels.
`libs/@local/flow-petri-net/src/compile-flow-definition/shared/flow-steps.ts`	Indexes steps and resolves payload shapes.
`libs/@local/flow-petri-net/src/compile-flow-definition/shared/colors.ts`	Defines token schemas and colours.
`libs/@local/flow-petri-net/src/compile-flow-definition/shared/action-subnet-ids.ts`	Defines subnet and port IDs.
`libs/@local/flow-petri-net/src/compile-flow-definition/generate-action-subnet.ts`	Generates action lifecycle subnets.
`libs/@local/flow-petri-net/src/compile-flow-definition/generate-action-subnet.test.ts`	Tests subnet ports and lifecycle structure.
`libs/@local/flow-petri-net/src/compile-flow-definition/compile-for-each-step.ts`	Compiles iteration and collection.
`libs/@local/flow-petri-net/src/compile-flow-definition/compile-action-step.ts`	Compiles action instances and connections.
`libs/@local/flow-petri-net/src/compile-flow-definition.ts`	Coordinates validation and net compilation.
`libs/@local/flow-petri-net/src/compile-flow-definition.test.ts`	Tests compatibility, routing, and determinism.
`libs/@local/flow-petri-net/README.md`	Documents architecture and limitations.
`libs/@local/flow-petri-net/package.json`	Declares exports, scripts, and dependencies.
`libs/@local/flow-petri-net/LICENSE.md`	Declares the package licence.
`libs/@local/flow-petri-net/eslint.config.js`	Configures package linting.
`libs/@local/flow-petri-net/docs/task-dependencies.json`	Records task dependency relationships.

_{Review effort: Balanced}

…om its consumer with ~, so no step id can collide with another key

…ther than its label, so kernels can address it

…tion's inputs takes, which its arcs alone don't say

… own, as other values do, so two consumers don't race for one token

…copy's value from its consumer with the step run id separator rather than a literal

cursor · 2026-10-20T09:10:42Z

PR Summary

Medium Risk
Introduces the canonical flow→net mapping and stable place/transition ids that future run marking will depend on, but it is not wired into production paths yet and execution semantics remain in follow-up work.

Overview
Adds @local/flow-petri-net, a new library (separate from @local/hash-isomorphic-utils so Petrinaut isn’t pulled into the whole graph) whose only public API is compileFlowDefinition: it validates a FlowDefinition, builds an SDCPN, runs ELK layout, and returns a Petrinaut-ready net. Nothing in the app calls it yet; follow-ups will visualize flows and run them from the net.

The compiler wires action steps as component instances of per-action subnets (ports, attempt/retry/give-up lifecycle, max_retries from step config) with root startStep / recordStepFailure transitions. placeValues decides where inputs, outputs, and for-each items live and adds copyOutput only when one producer must fan out to multiple readers and/or consumers (read vs consume arcs). For-each steps get iterator, item fan-out, pending tokens for nested steps, and collect/finish transitions.

Root metadata documents run bootstrap (flowInputs, pendingAtStart, flowOutputs), and transitions carry metadata.role and stepId (plus inputSources on startStep) for a future executor. IDs are stable UUIDv5s from readable keys via canonicalizePetrinautIds. Kernels are placeholders (no guards / real iterator–accumulator logic), so meaningful simulation is deferred to role-based execution.

Coverage includes compiling all in-repo hardcoded flows, routing cases, determinism, and Petrinaut import/model build checks; README documents net shape and known limitations.

^{Reviewed by Cursor Bugbot for commit ca0fef0. Bugbot is set up for automated code reviews on this repo. Configure here.}

Copilot

🟡 Changes recommended

Ambiguous output keys merge valid values and discard collected array results.

1 open issue

Prevent collisions between nested and collected output keys · New

4 resolved since last review

_{Review effort: Balanced}

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a79133c. Configure here.}

…tor, and name each value's place by its key, so no two outputs share a place or a name

…sts, rather than through a RunRequests place and startRun transition

kostandinang · 2026-10-20T16:23:28Z

+
+        if (key) {
+          getValue(key).consumers.push({
+            key: `${step.stepId}.${inputName}`,


These keys are rebuilt in compile-action-step.ts L90 and compile-for-each-step.ts L66/L115. Could placeValues own them?

kostandinang · 2026-10-20T16:23:28Z

+          getValue(key).consumers.push({
+            key: `${step.stepId}.${inputName}`,
+            label: `${step.stepId}.${inputName}`,
+            consumes: consumes(source),


A step inside a for-each that consumes an outer value only gets one token, so items after the first get stuck.

kostandinang · 2026-10-20T16:23:29Z

+ *   collected output.
+ * - A step that gives up puts a token in `FailedStepRuns`.
+ *
+ * Transitions carry their role in `metadata.role`, for the executor to interpret: the net has no guards or


there are placeholder kernels now.

kostandinang · 2026-10-20T16:33:36Z

+  "exports": {
+    "./compile-flow-definition": {
+      "types": "./src/compile-flow-definition.ts",
+      "default": "./dist/compile-flow-definition.js"
+    }
+  },


Only compileFlowDefinition is exported, but the executor and run view will need TransitionRole, the metadata shapes, and the key helpers. The README says ids are worked out from keys. Export those too?

kostandinang · 2026-10-20T16:33:47Z

+} from "@local/hash-isomorphic-utils/flows/types";
+
+describe("generateActionSubnet", () => {
+  it("gives an action a port per input and output, and one it gives up through", async () => {


some actions never get compiled in any test. Could we loop over every action definition here?

CiaranMn requested a balanced review from Copilot October 19, 2026 16:59

Copilot started reviewing on behalf of CiaranMn October 19, 2026 17:00

View session

CiaranMn added this pull request to stack #10074 October 19, 2026 17:01

Copilot AI reviewed Oct 19, 2026

View reviewed changes

vercel Bot deployed to Preview – hashdotdesign-tokens October 20, 2026 07:22

View deployment

vercel Bot deployed to Preview – petrinaut October 20, 2026 07:22

View deployment

vercel Bot deployed to Preview – petrinaut-docs October 20, 2026 07:23

View deployment

vercel Bot deployed to Preview – hash October 20, 2026 07:37

View deployment

vercel Bot temporarily deployed to Preview – petrinaut October 20, 2026 07:44 Inactive

vercel Bot temporarily deployed to Preview – petrinaut-docs October 20, 2026 07:44 Inactive

Base automatically changed from cm/fe-2006-flow-definition-entity-ids to main October 20, 2026 07:48

CiaranMn added 5 commits October 20, 2026 07:48

Add a compiler from flow definitions to Petri nets

0c61138

Give step instances keys of their own, and separate a copy's value fr…

35c43ad

…om its consumer with ~, so no step id can collide with another key

Name each flow input's place by the input's name, which is unique, ra…

7045005

…ther than its label, so kernels can address it

Record in each step's startStep transition which value each of its ac…

bdefbd1

…tion's inputs takes, which its arcs alone don't say

Give each step inside a for-each that consumes the item a copy of its…

415425e

… own, as other values do, so two consumers don't race for one token

CiaranMn force-pushed the cm/fe-1896-compile-flow-definitions-to-petri-nets branch from 757ad7f to 415425e Compare October 20, 2026 07:48

vercel Bot temporarily deployed to Preview – petrinaut October 20, 2026 07:48 Inactive

vercel Bot temporarily deployed to Preview – petrinaut-docs October 20, 2026 07:48 Inactive

vercel Bot deployed to Preview – hash October 20, 2026 07:51

View deployment

Generate instance and copy keys with named functions, and separate a …

a79133c

…copy's value from its consumer with the step run id separator rather than a literal

vercel Bot temporarily deployed to Preview – petrinaut-docs October 20, 2026 08:20 Inactive

vercel Bot temporarily deployed to Preview – petrinaut October 20, 2026 08:20 Inactive

CiaranMn marked this pull request as ready for review October 20, 2026 09:10

CiaranMn requested review from a team as code owners October 20, 2026 09:10

CiaranMn requested a balanced review from Copilot October 20, 2026 09:10

Copilot started reviewing on behalf of CiaranMn October 20, 2026 09:11

View session

Copilot AI reviewed Oct 20, 2026

View reviewed changes

Comment thread libs/@local/flow-petri-net/src/compile-flow-definition/shared/value-places.ts Outdated

cursor Bot reviewed Oct 20, 2026

View reviewed changes

Comment thread libs/@local/flow-petri-net/src/compile-flow-definition/shared/value-places.ts Outdated

Separate a step id from its output's name with the step run id separa…

382b84b

…tor, and name each value's place by its key, so no two outputs share a place or a name

vercel Bot temporarily deployed to Preview – petrinaut October 20, 2026 10:33 Inactive

vercel Bot temporarily deployed to Preview – petrinaut-docs October 20, 2026 10:33 Inactive

CiaranMn requested a review from kostandinang October 20, 2026 10:37

CiaranMn mentioned this pull request Oct 20, 2026

FE-1897: Show a flow as its Petri net in the flow and run pages #10119

Open

Start a run by putting its tokens in the places the net's metadata li…

ca0fef0

…sts, rather than through a RunRequests place and startRun transition

vercel Bot temporarily deployed to Preview – petrinaut-docs October 20, 2026 12:56 Inactive

vercel Bot temporarily deployed to Preview – petrinaut October 20, 2026 12:56 Inactive

kostandinang reviewed Oct 20, 2026

View reviewed changes

Navigation Menu

Repository navigation

FE-1887: Add a compiler from Flow Definitions to Petri nets - #10097

FE-1887: Add a compiler from Flow Definitions to Petri nets#10097
CiaranMn wants to merge 8 commits into
mainfrom
cm/fe-1896-compile-flow-definitions-to-petri-nets

CiaranMn commented Oct 19, 2026

Uh oh!

vercel Bot commented Oct 19, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot commented Oct 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

kostandinang Oct 20, 2026

Uh oh!

kostandinang Oct 20, 2026

Uh oh!

kostandinang Oct 20, 2026

Uh oh!

kostandinang Oct 20, 2026

Uh oh!

kostandinang Oct 20, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

Conversation

CiaranMn commented Oct 19, 2026

🌟 Purpose

🔍 Changes

What the executor and a run's view need from the net

⚠️ Known issues

Uh oh!

vercel Bot commented Oct 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kostandinang Oct 20, 2026

Choose a reason for hiding this comment

Uh oh!

kostandinang Oct 20, 2026

Choose a reason for hiding this comment

Uh oh!

kostandinang Oct 20, 2026

Choose a reason for hiding this comment

Uh oh!

kostandinang Oct 20, 2026

Choose a reason for hiding this comment

Uh oh!

kostandinang Oct 20, 2026

Choose a reason for hiding this comment

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

vercel Bot commented Oct 19, 2026 •

edited

Loading

cursor Bot commented Oct 20, 2026 •

edited

Loading