FE-1529: Start the optimizer service from the website's dev task and document the loop

[kube]

Important

Dev tooling and docs, nothing user-facing.

Summary

Before this PR, running the optimization loop locally needed a standalone launcher and a root dev:petrinaut-optimization script. Nothing in the architecture docs described the loop. A hard-killed run left its container behind and blocked the next one with "port is already allocated".

Loop becomes a flag on the website's dev task, turbo run dev --filter @apps/petrinaut-website -- --with-optimizer-service. A shell library behind it recovers from its own leftovers. Architecture docs describe the loop. Replaces #9388.

Links

• Ticket FE-1529
• Docs Running the loop locally

Changes

Dev task

• Website dev task gains --with-optimizer-service

  apps/petrinaut-website/scripts/dev.sh runs Vite as before.
  With the flag it first builds and starts the local Petrinaut Optimizer container and points the website at it through VITE_PETRINAUT_OPT_PROVIDER=service and PETRINAUT_OPT_ORIGIN.
  Every other argument after -- goes to Vite.

• Root dev:petrinaut-optimization script and the standalone launcher are gone

  Turborepo builds the website's workspace dependencies first: dev depends on codegen, which depends on ^build.

Service lifecycle

• Service lifecycle lives in a sourceable shell library

  scripts/optimizer-service.sh in @local/petrinaut-optimizer-client, sourced by any dev task that wants it.
  Starting Docker, polling a health endpoint and wrapping a dev server needs no Node.

• Library removes stopped containers earlier runs left behind

  Anchored name filter also covers the pid-suffixed names older launchers used.

• Library reuses a healthy optimizer already serving 127.0.0.1:4004

  Compose stack's optimizer and a bare uvicorn both qualify and are left alone on exit.
  Otherwise it builds petrinaut-opt:local and runs it read-only on loopback.

• Library stops only the container it started

  Matched by id, so two launchers never stop each other's.

Test coverage

None. Launcher is exercised by hand.

How to test

• turbo run dev --filter @apps/petrinaut-website -- --with-optimizer-service
• kill -9 launcher process
• Expect leaked container to survive
• Run same command again
• Expect "Removing leftover Petrinaut Opt dev container", rebuild, then Vite
• Open http://localhost:5173/optimization and create study
• Start compose stack's optimizer, run same command
• Expect "Reusing the optimizer already serving" and optimizer left running on exit
• turbo run dev --filter @apps/petrinaut-website without flag
• Expect Vite alone, as before

[vercel]

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

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

1 Skipped Deployment

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

The merge-base changed after approval.

[github-actions]

Benchmark results

@rust/hash-graph-benches – Integrations

policy_resolution_large

Function	Value	Mean	Flame graphs
resolve_policies_for_actor	user: empty, selectivity: high, policies: 2002	$$27.5 \mathrm{ms} \pm 252 \mathrm{μs}\left({\color{gray}-0.898 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$3.41 \mathrm{ms} \pm 18.7 \mathrm{μs}\left({\color{gray}-0.251 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 1002	$$12.6 \mathrm{ms} \pm 120 \mathrm{μs}\left({\color{gray}-2.986 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: high, policies: 3314	$$43.0 \mathrm{ms} \pm 360 \mathrm{μs}\left({\color{gray}-3.641 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: low, policies: 1	$$14.4 \mathrm{ms} \pm 197 \mathrm{μs}\left({\color{gray}-0.169 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: medium, policies: 1527	$$24.4 \mathrm{ms} \pm 193 \mathrm{μs}\left({\color{gray}-2.063 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 2078	$$28.2 \mathrm{ms} \pm 202 \mathrm{μs}\left({\color{gray}-1.703 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$3.79 \mathrm{ms} \pm 29.2 \mathrm{μs}\left({\color{gray}2.36 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 1033	$$13.6 \mathrm{ms} \pm 103 \mathrm{μs}\left({\color{gray}-2.828 \mathrm{\%}}\right) $$	Flame Graph

policy_resolution_medium

Function	Value	Mean	Flame graphs
resolve_policies_for_actor	user: empty, selectivity: high, policies: 102	$$3.80 \mathrm{ms} \pm 23.3 \mathrm{μs}\left({\color{gray}-1.361 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$3.01 \mathrm{ms} \pm 15.7 \mathrm{μs}\left({\color{gray}-0.621 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 52	$$3.37 \mathrm{ms} \pm 20.9 \mathrm{μs}\left({\color{gray}-0.548 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: high, policies: 269	$$5.22 \mathrm{ms} \pm 37.2 \mathrm{μs}\left({\color{gray}-0.387 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: low, policies: 1	$$3.54 \mathrm{ms} \pm 20.5 \mathrm{μs}\left({\color{gray}0.510 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: medium, policies: 108	$$4.16 \mathrm{ms} \pm 24.6 \mathrm{μs}\left({\color{gray}-0.137 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 133	$$4.51 \mathrm{ms} \pm 38.6 \mathrm{μs}\left({\color{gray}1.49 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$3.47 \mathrm{ms} \pm 24.8 \mathrm{μs}\left({\color{gray}-1.397 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 63	$$4.26 \mathrm{ms} \pm 41.6 \mathrm{μs}\left({\color{gray}3.28 \mathrm{\%}}\right) $$	Flame Graph

policy_resolution_none

Function	Value	Mean	Flame graphs
resolve_policies_for_actor	user: empty, selectivity: high, policies: 2	$$2.62 \mathrm{ms} \pm 19.5 \mathrm{μs}\left({\color{gray}-2.403 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$2.52 \mathrm{ms} \pm 18.0 \mathrm{μs}\left({\color{gray}-1.293 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 2	$$2.60 \mathrm{ms} \pm 24.1 \mathrm{μs}\left({\color{gray}-3.501 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 8	$$2.87 \mathrm{ms} \pm 20.2 \mathrm{μs}\left({\color{gray}-4.168 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$2.63 \mathrm{ms} \pm 14.5 \mathrm{μs}\left({\color{lightgreen}-5.141 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 3	$$2.84 \mathrm{ms} \pm 18.0 \mathrm{μs}\left({\color{lightgreen}-5.179 \mathrm{\%}}\right) $$	Flame Graph

policy_resolution_small

Function	Value	Mean	Flame graphs
resolve_policies_for_actor	user: empty, selectivity: high, policies: 52	$$3.05 \mathrm{ms} \pm 20.0 \mathrm{μs}\left({\color{gray}-0.793 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$2.74 \mathrm{ms} \pm 16.2 \mathrm{μs}\left({\color{gray}-0.772 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 26	$$2.95 \mathrm{ms} \pm 21.6 \mathrm{μs}\left({\color{gray}-1.231 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: high, policies: 94	$$3.46 \mathrm{ms} \pm 22.0 \mathrm{μs}\left({\color{gray}0.085 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: low, policies: 1	$$2.96 \mathrm{ms} \pm 19.5 \mathrm{μs}\left({\color{gray}-1.356 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: medium, policies: 27	$$3.26 \mathrm{ms} \pm 21.9 \mathrm{μs}\left({\color{gray}0.159 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 66	$$3.36 \mathrm{ms} \pm 21.0 \mathrm{μs}\left({\color{gray}-2.356 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$2.98 \mathrm{ms} \pm 24.7 \mathrm{μs}\left({\color{gray}0.114 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 29	$$3.29 \mathrm{ms} \pm 22.0 \mathrm{μs}\left({\color{gray}-0.036 \mathrm{\%}}\right) $$	Flame Graph

read_scaling_complete

Function	Value	Mean	Flame graphs
entity_by_id;one_depth	1 entities	$$42.0 \mathrm{ms} \pm 271 \mathrm{μs}\left({\color{gray}-0.996 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	10 entities	$$32.1 \mathrm{ms} \pm 189 \mathrm{μs}\left({\color{lightgreen}-5.777 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	25 entities	$$35.3 \mathrm{ms} \pm 314 \mathrm{μs}\left({\color{gray}-3.411 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	5 entities	$$31.7 \mathrm{ms} \pm 314 \mathrm{μs}\left({\color{gray}-1.687 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	50 entities	$$41.5 \mathrm{ms} \pm 307 \mathrm{μs}\left({\color{gray}-4.360 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	1 entities	$$49.5 \mathrm{ms} \pm 389 \mathrm{μs}\left({\color{gray}-1.443 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	10 entities	$$39.7 \mathrm{ms} \pm 345 \mathrm{μs}\left({\color{gray}-1.657 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	25 entities	$$90.2 \mathrm{ms} \pm 623 \mathrm{μs}\left({\color{gray}1.59 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	5 entities	$$33.1 \mathrm{ms} \pm 226 \mathrm{μs}\left({\color{gray}-3.477 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	50 entities	$$252 \mathrm{ms} \pm 1.01 \mathrm{ms}\left({\color{lightgreen}-8.866 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	1 entities	$$10.5 \mathrm{ms} \pm 66.4 \mathrm{μs}\left({\color{gray}-0.720 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	10 entities	$$10.6 \mathrm{ms} \pm 72.6 \mathrm{μs}\left({\color{gray}-1.516 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	25 entities	$$10.8 \mathrm{ms} \pm 95.4 \mathrm{μs}\left({\color{gray}1.80 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	5 entities	$$10.5 \mathrm{ms} \pm 70.3 \mathrm{μs}\left({\color{gray}0.050 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	50 entities	$$10.6 \mathrm{ms} \pm 89.1 \mathrm{μs}\left({\color{gray}-0.639 \mathrm{\%}}\right) $$	Flame Graph

read_scaling_linkless

Function	Value	Mean	Flame graphs
entity_by_id	1 entities	$$10.5 \mathrm{ms} \pm 58.3 \mathrm{μs}\left({\color{gray}-0.673 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10 entities	$$10.5 \mathrm{ms} \pm 62.5 \mathrm{μs}\left({\color{gray}0.231 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	100 entities	$$10.6 \mathrm{ms} \pm 62.1 \mathrm{μs}\left({\color{gray}0.250 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1000 entities	$$10.5 \mathrm{ms} \pm 74.0 \mathrm{μs}\left({\color{gray}0.220 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10000 entities	$$10.8 \mathrm{ms} \pm 79.5 \mathrm{μs}\left({\color{gray}-0.322 \mathrm{\%}}\right) $$	Flame Graph

representative_read_entity

Function	Value	Mean	Flame graphs
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/block/v/1	$$10.8 \mathrm{ms} \pm 72.0 \mathrm{μs}\left({\color{gray}-1.178 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/book/v/1	$$10.9 \mathrm{ms} \pm 75.6 \mathrm{μs}\left({\color{gray}0.714 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/building/v/1	$$11.0 \mathrm{ms} \pm 94.8 \mathrm{μs}\left({\color{gray}1.26 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/organization/v/1	$$11.0 \mathrm{ms} \pm 82.4 \mathrm{μs}\left({\color{gray}0.930 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/page/v/2	$$10.8 \mathrm{ms} \pm 75.4 \mathrm{μs}\left({\color{gray}0.385 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/person/v/1	$$10.9 \mathrm{ms} \pm 63.0 \mathrm{μs}\left({\color{gray}1.79 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/playlist/v/1	$$10.9 \mathrm{ms} \pm 80.9 \mathrm{μs}\left({\color{gray}0.702 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/song/v/1	$$10.9 \mathrm{ms} \pm 85.7 \mathrm{μs}\left({\color{gray}0.159 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/uk-address/v/1	$$10.8 \mathrm{ms} \pm 78.7 \mathrm{μs}\left({\color{gray}0.184 \mathrm{\%}}\right) $$	Flame Graph

representative_read_entity_type

Function	Value	Mean	Flame graphs
get_entity_type_by_id	Account ID: bf5a9ef5-dc3b-43cf-a291-6210c0321eba	$$8.18 \mathrm{ms} \pm 55.2 \mathrm{μs}\left({\color{gray}-0.286 \mathrm{\%}}\right) $$	Flame Graph

representative_read_multiple_entities

Function	Value	Mean	Flame graphs
entity_by_property	traversal_paths=0	0	$$55.1 \mathrm{ms} \pm 340 \mathrm{μs}\left({\color{gray}1.04 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=255	1,resolve_depths=inherit:1;values:255;properties:255;links:127;link_dests:126;type:true	$$109 \mathrm{ms} \pm 980 \mathrm{μs}\left({\color{gray}2.01 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:0;links:0;link_dests:0;type:false	$$64.0 \mathrm{ms} \pm 475 \mathrm{μs}\left({\color{gray}3.58 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:0;links:1;link_dests:0;type:true	$$73.1 \mathrm{ms} \pm 541 \mathrm{μs}\left({\color{gray}3.18 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:2;links:1;link_dests:0;type:true	$$82.0 \mathrm{ms} \pm 720 \mathrm{μs}\left({\color{gray}1.69 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:2;properties:2;links:1;link_dests:0;type:true	$$87.7 \mathrm{ms} \pm 694 \mathrm{μs}\left({\color{gray}2.70 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=0	0	$$43.4 \mathrm{ms} \pm 299 \mathrm{μs}\left({\color{gray}2.12 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=255	1,resolve_depths=inherit:1;values:255;properties:255;links:127;link_dests:126;type:true	$$72.0 \mathrm{ms} \pm 492 \mathrm{μs}\left({\color{gray}1.20 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:0;links:0;link_dests:0;type:false	$$50.1 \mathrm{ms} \pm 390 \mathrm{μs}\left({\color{gray}2.58 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:0;links:1;link_dests:0;type:true	$$59.7 \mathrm{ms} \pm 556 \mathrm{μs}\left({\color{gray}2.54 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:2;links:1;link_dests:0;type:true	$$60.7 \mathrm{ms} \pm 437 \mathrm{μs}\left({\color{gray}0.611 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:2;properties:2;links:1;link_dests:0;type:true	$$61.4 \mathrm{ms} \pm 435 \mathrm{μs}\left({\color{gray}1.60 \mathrm{\%}}\right) $$

scenarios

Function	Value	Mean	Flame graphs
full_test	query-limited	$$127 \mathrm{ms} \pm 851 \mathrm{μs}\left({\color{gray}4.32 \mathrm{\%}}\right) $$	Flame Graph
full_test	query-unlimited	$$138 \mathrm{ms} \pm 754 \mathrm{μs}\left({\color{gray}3.45 \mathrm{\%}}\right) $$	Flame Graph
linked_queries	query-limited	$$17.6 \mathrm{ms} \pm 164 \mathrm{μs}\left({\color{lightgreen}-22.842 \mathrm{\%}}\right) $$	Flame Graph
linked_queries	query-unlimited	$$533 \mathrm{ms} \pm 1.20 \mathrm{ms}\left({\color{gray}-1.255 \mathrm{\%}}\right) $$	Flame Graph