FE-1237: Add optional per-place token capacity

[kube]

🌟 What is the purpose of this PR?

A place can now declare a maximum number of tokens it will hold. Raised for supply-chain style modelling, where finite storage and buffers are the point rather than an edge case.

It is also the keystone for what comes after: capacity is what converts frames from growable to fixed-size, which is the precondition for a fixed-layout GPU or WASM path.

🔗 Related links

• FE-1237: Place capacity — limit the number of tokens allowed on a place (internal)
• Raised by Dora Ma in #lib-petrinaut (internal)

🚫 Blocked by

• FE-1314: Run experiment runs in parallel across workers #9162 — stacked on top of it

🔍 What does this change?

Capacity participates in transition enablement, following the standard Petri-net capacity constraint: a transition cannot fire if firing would take any output place above its capacity.

Two details that matter:

• Output tokens apply at the end of a frame, so the check folds in what transitions earlier in the same frame have already committed. Several transitions feeding one capped place cannot collectively overflow it.
• Deadlock detection uses the same check. Without it, a net whose only remaining transitions are blocked by full output places would step to maxTime with nothing happening instead of being reported as deadlocked.

Nets that declare no capacities are unaffected — the constraint tables are empty and the hot path skips them.

// A place holding at most 20 tokens.
{ id: "p_buffer", name: "Buffer", capacity: 20 }

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

⚠️ Known issues

Capacity is not retro-applied: a net whose initial marking already exceeds a capacity it later declares is not rejected, because enablement blocks transitions rather than repairing state.

🐾 Next steps

The fixed-size frame layout this unlocks (SoA, WASM linear memory) is not built here — the runtime still uses growable frames. The WebGPU backend stacked above this one is the first consumer that requires capacities.

🛡 What tests cover this?

engine/capacity.test.ts covers the constraint tables and headroom check; monte-carlo/capacity.test.ts covers end-of-frame accumulation across several transitions feeding one place, and deadlock reporting.

❓ How to test this?

1. Check out the branch and open a net in the editor.
2. Select a place, enable Token capacity, and set a small value.
3. Run the simulation and confirm transitions feeding that place stop firing at the cap, and that 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 8, 2026 1:13am
petrinaut	Ready	Preview	Aug 8, 2026 1:13am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored		Aug 8, 2026 1:13am