FE-740: Add Read Arcs

[kube]

TODO

• Fix the AI addArc
• Do adjustments from AI reviews

🌟 What is the purpose of this PR?

This PR introduces Read Arcs in Petrinaut.

Read Arcs work like a normal Arc, but they are read-only. They can be used to read data from an Arc without modifying it.

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 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.

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?

❓ How to test this?

1. Checkout the branch / view the deployment
2. Try X
3. Confirm that Y

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	May 27, 2026 9:33pm
petrinaut	Ready	Preview, Comment	May 27, 2026 9:33pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored		May 27, 2026 9:33pm

[cursor]

PR Summary

Medium Risk
Changes discrete-transition firing and token removal in the simulation engine, but behavior is narrowly scoped to arc typing with broad automated test coverage.

Overview
Adds read input arcs: they gate firing like standard arcs (enough tokens at the required weight) and expose coloured tokens to transition lambda and kernel input, but do not remove those tokens when the transition fires.

Core model, Zod schemas, and addArc / updateArcType mutations now accept "read"; file import and clipboard parsing keep "read" while still defaulting missing types to standard. The discrete simulation and Monte Carlo paths treat read arcs like standard for enablement and token combination input, and only standard arcs contribute to the removal map; LSP virtual types include read inputs like standard (inhibitors still omitted).

The editor surfaces read arcs in arc/transition properties, list badges, and canvas styling (distinct dash from inhibitor). User docs and AI prompts describe read vs consume semantics. Tests cover mutations, import/clipboard, enablement, firing, full-frame execution, Monte Carlo, and LSP completions.

^{Reviewed by Cursor Bugbot for commit 59cbd83. 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.