FE-1237: Add optional per-place token capacity

[kube]

🌟 What is the purpose of this PR?

Adds an optional per-place token capacity, set from the place properties panel. Dora Ma requested it for supply-chain models with finite storage. It also converts frames from growable to fixed-size, which the GPU backend (#9179) requires.

This PR sits above #9162 in stack #9280, and #9178 builds on it.

🔗 Related links

• FE-1237 (internal): this PR.
• Requested by Dora Ma in #lib-petrinaut (internal).

🚫 Blocked by

• FE-1314: Run experiment runs in parallel across workers #9162

🔍 What does this change?

A transition cannot fire if firing would take an output place above its capacity. This is the standard Petri-net capacity constraint.

{ id: "p_buffer", name: "Buffer", capacity: 20 }

• Output tokens apply at the end of a frame, and the check counts what earlier transitions in the same frame already committed, so several transitions feeding one capped place cannot collectively overflow it.
• Deadlock detection uses the same check, so a net blocked only by full output places reports as deadlocked instead of stepping to maxTime.
• buildSimulation rejects an initial marking that exceeds a place's capacity, with a message naming the place.
• A net that declares no capacities gets empty constraint tables, and the hot path skips them.

Review fixes

• The interactive stepping path (executeTransitions) now threads a pending-output tally into the capacity check, so several transitions feeding one capped place in a single step can no longer collectively overflow it. This matches the Monte Carlo path and the behaviour docs/simulation.md already promised. A regression test in compute-next-frame.test.ts pins it: two producers feed one capacity-1 place, and exactly one fires.
• The initial-marking check in buildSimulation now normalizes the capacity the same way the runtime does, so a malformed capacity that runs unbounded cannot reject a marking.
• The capacity NumberInput gained a max of 4294967294, one below the engine's unbounded sentinel.
• The capacity checkbox's comment claimed the value defaults to the current token count. It now states the real behaviour: the capacity starts at 1, and a marking above the cap fails the build with a message naming the place.

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

🐾 Next steps

Build the fixed-size frame layout (SoA over WASM linear memory). The runtime still uses growable frames.

🛡 What tests cover this?

• engine/capacity.test.ts covers the constraint tables and the headroom check.
• monte-carlo/capacity.test.ts covers end-of-frame accumulation across several transitions feeding one place, and deadlock reporting.
• engine/compute-next-frame.test.ts covers the interactive stepping path holding a capacity when two transitions feed one place in a single step.

❓ How to test this?

1. Select a place, switch on Token capacity, and set a small value.
2. Run the simulation. Transitions feeding that place stop firing at the cap, and the run reports as deadlocked once nothing else can fire.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 22, 2026 3:06am
petrinaut	Ready	Preview	Aug 22, 2026 3:06am
petrinaut-docs	Ready	Preview	Aug 22, 2026 3:06am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 22, 2026 3:06am

[cursor]

PR Summary

Medium Risk
Changes simulation enablement and deadlock on both interactive and Monte Carlo engines. Nets without capacities keep empty constraint tables, but incorrect headroom logic would alter firing and completion.

Overview
Adds optional per-place token capacity as a Petri-net enablement constraint: a transition cannot fire if the net change would take any output place over its cap. Self-loops are not blocked; read/inhibitor arcs do not free room. Output is applied at end of frame, so pending counts stop several producers from jointly overflowing one place.

buildSimulation rejects an initial marking above capacity. Deadlock detection includes the same check so a net blocked only by full outputs stops instead of running to maxTime. Uncapped nets get empty constraint tables and skip the hot path.

The place properties panel can enable a cap (default 1). Docs and tests cover constraint tables, Monte Carlo stepping, and interactive two-producer overflow. Frames remain growable; capacity is not in the HIR fingerprint.

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

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[cursor]

Capacity default ignores token count

Medium Severity

Enabling Token capacity always writes capacity: 1, while the comment says the default should be the current token count so the limit cannot invalidate an existing initial marking. Places already holding more than one token become illegal at build time until the user raises the cap manually.

 

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

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[cursor]

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

There are 2 total unresolved issues (including 1 from previous review).

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

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