FE-1509: Add the structural analyses — cycles and initial places

[kube]

Important

Pure algorithms and tests, nothing user-facing on its own.

Summary

Before this PR, the notebook lists cells and draws the whole-net graph, but computes nothing structural about the net. Feedback loops and places the initial state must seed are invisible, and both are the questions a reader of a net asks first.

Adds the two analyses as pure functions over places, transitions and arcs: cycle detection and initial-place analysis. Nothing consumes them yet; the layer above surfaces both, so this PR reviews as two algorithms and their test suites, plus an authored page recording why each algorithm was chosen.

Links

• Ticket FE-1509
• Docs Notebook graph analyses

Changes

• net-cycles finds every feedback group as a strongly connected component

  Iterative Tarjan, so deep nets cannot blow the call stack. Components sized above one, labelled in document order.
  SCCs rather than elementary cycles because their count can be exponential and the reader's question is which nodes feed back into each other.

• net-siphons finds the place groups the initial marking must cover

  A minimal siphon is a place set nothing in the net can seed, which unifies plain source places with resource pools that only circulate what they start with.
  Found per place by a greedy shrink from the maximal siphon. Groups overlapping a smaller reported group are dropped for readability.

• Stale arcs exclude their transition from the siphon analysis

  A transition referencing a deleted place can never fire, so reading it as a live source would wrongly suppress a seeding requirement.

• Nets above 100 places skip the siphon analysis

  The shrink is cubic in the place count. A dense 100-place net computes in about 100ms; larger nets skip rather than stall a render.

Test coverage

• net-cycles.test.ts:

  Chains, two-node and four-node loops, disjoint loops, membership lookup, document-order labels.

• net-siphons.test.ts:

  Source places, circulating pools, containment dedupe, stale-arc exclusion, and the example models end to end.

How to test

• npx turbo run test:unit --filter @hashintel/petrinaut
• Expect net-cycles and net-siphons suites green

[vercel]

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

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 3, 2026 10:54pm UTC
petrinaut	Ready	Preview	Sep 3, 2026 10:54pm UTC
petrinaut-docs	Ready	Preview	Sep 3, 2026 10:54pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 3, 2026 10:54pm UTC