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.
It also converts frames from growable to fixed-size, which the GPU backend (#9179) requires.

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 27, 2026 6:33pm
petrinaut	Ready	Preview	Aug 27, 2026 6:33pm
petrinaut-docs	Ready	Preview	Aug 27, 2026 6:33pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 27, 2026 6:33pm

[cursor]

PR Summary

Medium Risk
Touches core transition enablement and frame stepping in both interactive and Monte Carlo engines, but the feature is opt-in and heavily covered by new unit and integration tests.

Overview
Places can now declare an optional token capacity (schema, types, and a Token capacity control in the place properties panel). A transition is structurally disabled if firing would push any bounded output place over its limit—same idea as missing input tokens—using net change per firing (self-loops at a full place still work; read/inhibitor arcs do not free room).

The engine precomputes per-transition capacity constraints at build time, stores dense placeCapacities on EngineFrameLayout, and skips checks when no place is capped. buildSimulation rejects initial markings above a place’s normalized capacity. Both stepping paths (executeTransitions / computePossibleTransition and Monte Carlo advanceRun) thread pendingOutputCounts so end-of-frame output application cannot let multiple producers overflow one capped place in a single step. Deadlock / structural enablement treats full outputs like missing inputs.

Docs and arch notes are updated; nets without capacities keep empty constraint tables on the hot path.

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

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