FE-740: Add Read Arcs

[kube]

🌟 What is the purpose of this PR?

This PR introduces Read Arcs in Petrinaut.

Read Arcs work like normal input arcs for enablement: the source place must contain at least weight tokens. For coloured places, those tokens are provided to Lambda and TransitionKernel under input.<PlaceName>, with tuple length equal to the arc weight.

The difference from standard arcs is consumption. When a transition fires, standard input arc tokens are removed immediately, while read arc tokens remain in their source place. This lets a transition inspect shared state or token attributes without moving that token through the transition.

They are almost syntactic sugar for a self-loop (same Place as input and output of transition with same token), but they are convenient in the sense that they prevent the user from accidentally modifying the data they are trying to read.

Change in runtime behaviour

Currently, for simulating the same behaviour you could use this self-loop pattern.

graph LR
  InputPlace(InputPlace)
  TransitionA["Reader A"]
  TransitionB["Reader B"]
  
  TransitionA --> InputPlace
  TransitionB --> InputPlace
  
  InputPlace --> TransitionA
  InputPlace --> TransitionB

Loading

Though given the tokens of Reader A would be consumed temporarily in the frame during which the transition would be happening, Reader B would not be able to consume it until the next frame.

With Read Arcs, both these transitions would be triggered in the same frame.

Impacted areas

• Core SDCPN model: InputArc.type now accepts "read" alongside "standard" and "inhibitor".
• Validation/import paths: runtime schemas, file import, and clipboard import preserve read arcs while continuing to default older payloads to "standard".
• Mutations and AI tools: addArc can create typed input arcs directly, and updateArcType can switch an input arc to read.
• Simulation engines: read arcs participate in enablement and token combination enumeration, but are excluded from token removal in both standard and Monte Carlo execution.
• LSP/UI/docs: read arcs contribute typed input properties, are selectable/rendered distinctly in the editor, and are documented alongside standard and inhibitor arcs.

Edge cases

• Uncoloured read arcs still gate enablement but do not appear in lambda/kernel input, matching uncoloured standard arc behaviour.
• A transition with only read arcs can fire repeatedly while inspecting the same tokens unless a predicate, output effect, time limit, or another input stops it.
• Arc identity remains place-to-transition based; this does not add support for parallel input arcs between the same place and transition.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies an npm-publishable library and I have added a changeset file(s)

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

🛡 What tests cover this?

• Structural enablement tests for read arcs.
• Single-step and full-frame simulation tests proving read arc tokens reach lambda/kernel input and are not removed.
• Monte Carlo coverage for non-consuming read arcs.
• LSP completion coverage for read arc token inputs.
• File and clipboard parsing coverage for "read" arc types.
• AI tool/schema tests for typed addArc inputs.

Verified with:

• yarn workspace @hashintel/petrinaut-core test:unit
• yarn workspace @hashintel/petrinaut-core lint:tsc
• yarn workspace @hashintel/petrinaut-core lint:eslint
• yarn workspace @hashintel/petrinaut-core build
• yarn workspace @hashintel/petrinaut test:unit
• yarn workspace @hashintel/petrinaut lint:tsc
• yarn workspace @hashintel/petrinaut lint:eslint

❓ How to test this?

1. Checkout the branch or view the deployment.
2. Create an input arc from a place to a transition and set its type to Read in the arc properties panel.
3. Run a simulation where the transition reads a coloured token from that place.
4. Confirm the transition can use the token data while the source token remains in place after firing.
5. For shared-state behaviour, add two transitions reading the same place and confirm both can fire in the same frame.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	Jun 3, 2026 9:13pm
petrinaut	Ready	Preview, Comment	Jun 3, 2026 9:13pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Jun 3, 2026 9:13pm

[cursor]

PR Summary

Medium Risk
Changes discrete transition firing and token removal in core and Monte Carlo paths; behavior is well covered by tests but incorrect edge cases could affect simulation correctness.

Overview
Adds read as a third input arc type alongside standard and inhibitor. Read arcs gate firing like standard arcs (enough tokens required) and supply coloured tokens to lambdas/kernels, but do not remove those tokens when a transition fires—so multiple transitions can inspect the same place in one simulation step.

Core: InputArc.type includes "read"; addArc accepts optional type on input arcs (rejected on outputs); import/clipboard still default missing types to "standard". Single-run and Monte Carlo engines treat read arcs like standard for enablement and token enumeration, but skip them in removal logic. LSP virtual input types include read arc places like standard arcs.

Editor: Arc properties offer Read; transition arc lists show Read/Inhibitor badges; canvas uses a dotted stroke and dot marker for read arcs. Docs and AI prompts describe read semantics and shared-state patterns.

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

[augmentcode]

🤖 Augment PR Summary

Summary: Adds Read Arcs to Petrinaut SDCPNs: input arcs that require and expose tokens to transition code but do not consume them on firing.

Changes:

• Extends the core SDCPN model/type system to allow InputArc.type = "read" alongside standard and inhibitor.
• Updates validation/action schemas and mutation inputs so addArc and updateArcType can create/switch read arcs while defaulting older payloads to standard.
• Preserves read arc types across import/export surfaces (file-format parsing and clipboard serialization/parsing).
• Updates the simulation engine and Monte Carlo execution paths so read arcs participate in enablement and token input enumeration, but are excluded from token removal.
• Updates LSP virtual typing so read arcs contribute to typed input.PlaceName (inhibitors still excluded).
• Updates UI: read arc option in arc properties, read/inhibitor badges in arc lists, and distinct canvas rendering (dash pattern) for read arcs.

Technical Notes: Adds targeted unit tests covering schema preservation, enablement logic, lambda/kernel inputs, and non-consuming behavior for read arcs.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. No suggestions at this time.

Comment augment review to trigger a new review at any time.

[Copilot]

Pull request overview

This PR adds Read Arcs to Petrinaut/SDCPN as a new input-arc type ("read") that participates in structural enablement and provides tokens to lambda/kernel input (like standard arcs), but does not consume tokens when the transition fires. This extends core simulation semantics (engine + Monte Carlo), propagates the new arc type through schemas/import/clipboard/LSP, and updates the editor UI + docs to support authoring and visualization.

Changes:

• Extend the core SDCPN model and schemas to support InputArcType = "standard" | "read" | "inhibitor" and preserve "read" through file/clipboard formats and mutations.
• Update simulation execution paths (engine + Monte Carlo) so only standard arcs remove tokens, while read arcs remain available in the same frame.
• Add UI affordances and documentation for selecting/readability/rendering of read arcs, plus tests covering semantics, import/clipboard, and LSP typing.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
libs/@hashintel/petrinaut/src/ui/views/SDCPN/reactflow-types.ts	Types UI edge data arcType from core InputArc["type"] so "read" is representable.
libs/@hashintel/petrinaut/src/ui/views/SDCPN/components/arc.tsx	Render read arcs with distinct dash pattern/linecap; refactor dash selection.
libs/@hashintel/petrinaut/src/ui/views/Editor/panels/PropertiesPanel/transition-properties/subviews/main.tsx	Pass input arc.type into arc list items so read arcs are visible in transition panel.
libs/@hashintel/petrinaut/src/ui/views/Editor/panels/PropertiesPanel/arc-properties/main.tsx	Allow selecting "read" in arc properties for input arcs; align types with core.
libs/@hashintel/petrinaut/src/ui/components/arc-item.tsx	Display a “Read”/“Inhibitor” badge for non-standard input arcs in lists.
libs/@hashintel/petrinaut/docs/useful-patterns.md	Add a modeling pattern section recommending read arcs for shared-state checks.
libs/@hashintel/petrinaut/docs/simulation.md	Document read-arc behavior during discrete transition evaluation/consumption.
libs/@hashintel/petrinaut/docs/README.md	Update docs index blurb to include read arcs.
libs/@hashintel/petrinaut/docs/petri-net-extensions.md	Define read arcs and clarify tokensByPlace inclusion/consumption semantics.
libs/@hashintel/petrinaut/docs/drawing-a-net.md	Update editor guidance to mention Standard/Read/Inhibitor input arc types.
libs/@hashintel/petrinaut/ANALYSIS.md	Add internal design/edge-case/test coverage analysis for read arcs.
libs/@hashintel/petrinaut-core/src/types/sdcpn.ts	Introduce InputArcType and extend InputArc.type to include "read".
libs/@hashintel/petrinaut-core/src/simulation/monte-carlo/transition-effect.ts	Ensure Monte Carlo effects only remove tokens for standard arcs (not read).
libs/@hashintel/petrinaut-core/src/simulation/monte-carlo/monte-carlo-simulator.test.ts	Add test proving read arcs don’t consume tokens in Monte Carlo runs.
libs/@hashintel/petrinaut-core/src/simulation/monte-carlo/frame-operations.ts	Clarify deadlock/structural enablement checks include read arc availability.
libs/@hashintel/petrinaut-core/src/simulation/engine/types.ts	Widen compiled input arc typing to InputArcType for engine paths.
libs/@hashintel/petrinaut-core/src/simulation/engine/execute-transitions.test.ts	Add engine test ensuring read tokens remain after firing while still being readable.
libs/@hashintel/petrinaut-core/src/simulation/engine/compute-possible-transition.ts	Exclude read arcs from removal map while still enumerating their token combinations.
libs/@hashintel/petrinaut-core/src/simulation/engine/compute-possible-transition.test.ts	Add test asserting read tokens reach lambda/kernel input and are not removed.
libs/@hashintel/petrinaut-core/src/simulation/engine/check-transition-enablement.ts	Extend enablement logic/comments so inhibitors invert condition; read behaves like standard.
libs/@hashintel/petrinaut-core/src/simulation/engine/check-transition-enablement.test.ts	Add enablement tests specifically for read arcs.
libs/@hashintel/petrinaut-core/src/schemas/entity-schemas.ts	Extend Zod schemas/docs for input arcs to include "read" and updated semantics.
libs/@hashintel/petrinaut-core/src/lsp/lib/generate-virtual-files.ts	Ensure read arcs contribute typed input properties like standard arcs (inhibitors excluded).
libs/@hashintel/petrinaut-core/src/lsp/lib/create-sdcpn-language-service.test.ts	Add completions test covering read-arc input token properties.
libs/@hashintel/petrinaut-core/src/file-format/types.ts	Preserve "read" during file import while defaulting missing type to "standard".
libs/@hashintel/petrinaut-core/src/file-format/parse-sdcpn-file.test.ts	Add import test verifying "read" arc types are preserved.
libs/@hashintel/petrinaut-core/src/default-codes.ts	Update default code comments to mention coloured standard/read inputs.
libs/@hashintel/petrinaut-core/src/clipboard/types.ts	Preserve "read" during clipboard parse while defaulting missing type to "standard".
libs/@hashintel/petrinaut-core/src/clipboard/serialize.test.ts	Add clipboard test verifying "read" arc types are preserved.
libs/@hashintel/petrinaut-core/src/ai.ts	Update AI-facing guidance to describe read arc token exposure without consumption.
libs/@hashintel/petrinaut-core/src/actions.ts	Allow addArc to create input arcs with explicit type (including "read").
libs/@hashintel/petrinaut-core/src/actions.test.ts	Add mutation test for adding/updating read input arcs.
libs/@hashintel/petrinaut-core/src/action-schemas.ts	Extend mutation schemas so addArc supports optional input type, and updateArcType supports "read".

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 35 out of 35 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 35 out of 35 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 38 out of 38 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 38 out of 38 changed files in this pull request and generated 2 comments.