SRE-982: Remove the graph API package's JavaScript surface

[TimDiekmann]

🌟 What is the purpose of this PR?

libs/@local/graph/api has no TypeScript. Its whole JavaScript surface was one exports entry pointing at the committed OpenAPI document, read by a single consumer — and that entry cannot survive the move to Cargo workspaces, since the crate will have no manifest to hang it on.

Splitting the directory would mean a package whose only content is a copy of a ten-thousand-line JSON document, so @local/hash-graph-client carries it instead. It already reads the document to generate itself, and every consumer already depends on it.

Builds on SRE-981.

🔍 What does this change?

• The client's codegen copies the document alongside the code it generates from it; the copy is ignored, like the rest of that package's generated output
• hash-ai-worker-ts imports it from the client and drops its now-unused dependency on the crate. The edge survives transitively, so a change to the document still selects the worker
• The crate's exports is gone; its manifest is now pure wiring

The document stays committed in the crate, so that a change to the API contract shows up in the diff of the pull request that makes it. That is worth more than the ten thousand lines cost.

Generating it instead would also put a Rust toolchain in the way of the deployment builds, which the note above the client's build task records as having broken before — though not of CI, which has one anyway.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

• are internal and do not require a docs change

🕸️ Does this require a change to the Turbo Graph?

• affected the execution graph, and the turbo.json's have been updated to reflect this

🐾 Next steps

SRE-983, then SRE-984.

❓ How to test this?

1. turbo run codegen --filter=@local/hash-graph-client, then check openapi.json sits beside the generated client
2. turbo run lint:tsc --filter=@apps/hash-ai-worker-ts
3. mise run sync:turborepo && git diff --exit-code '**/package.json'

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 29, 2026 7:40pm

3 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 29, 2026 7:40pm
petrinaut	Skipped		Aug 29, 2026 7:40pm
petrinaut-docs	Skipped		Aug 29, 2026 7:40pm

[cursor]

PR Summary

Low Risk
Packaging and import-path refactor with a single consumer; behavior depends on running client codegen before builds that import the copied spec.

Overview
Removes the JavaScript exports surface from @rust/hash-graph-api so the Rust crate no longer publishes openapi.json for TypeScript consumers (needed for the Cargo workspace move).

@local/hash-graph-client now copies the committed spec from ../../api/openapi/openapi.json during codegen, alongside the generated client; openapi.json is gitignored like other generated artifacts, and Turbo records it as a codegen output.

hash-ai-worker-ts imports the spec from @local/hash-graph-client/openapi.json and drops its direct @rust/hash-graph-api dependency; the worker still reaches the API crate transitively via the client’s dev dependency, so OpenAPI changes still pull the worker into the build graph.

The canonical OpenAPI document remains committed under the API crate for reviewable contract diffs.

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

[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	$$25.3 \mathrm{ms} \pm 230 \mathrm{μs}\left({\color{gray}-2.576 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$3.41 \mathrm{ms} \pm 17.7 \mathrm{μs}\left({\color{gray}-2.965 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 1002	$$12.2 \mathrm{ms} \pm 88.3 \mathrm{μs}\left({\color{gray}-0.861 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: high, policies: 3314	$$43.7 \mathrm{ms} \pm 378 \mathrm{μs}\left({\color{gray}1.77 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: low, policies: 1	$$14.3 \mathrm{ms} \pm 118 \mathrm{μs}\left({\color{lightgreen}-8.335 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: medium, policies: 1527	$$24.2 \mathrm{ms} \pm 241 \mathrm{μs}\left({\color{gray}-1.664 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 2078	$$26.4 \mathrm{ms} \pm 231 \mathrm{μs}\left({\color{gray}-2.663 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$3.73 \mathrm{ms} \pm 22.2 \mathrm{μs}\left({\color{gray}-4.484 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 1033	$$13.4 \mathrm{ms} \pm 118 \mathrm{μs}\left({\color{gray}-2.565 \mathrm{\%}}\right) $$	Flame Graph

policy_resolution_medium

Function	Value	Mean	Flame graphs
resolve_policies_for_actor	user: empty, selectivity: high, policies: 102	$$3.72 \mathrm{ms} \pm 24.8 \mathrm{μs}\left({\color{gray}-0.792 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$3.04 \mathrm{ms} \pm 21.6 \mathrm{μs}\left({\color{gray}1.16 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 52	$$3.37 \mathrm{ms} \pm 22.5 \mathrm{μs}\left({\color{gray}0.268 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: high, policies: 269	$$5.11 \mathrm{ms} \pm 31.8 \mathrm{μs}\left({\color{gray}-0.636 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: low, policies: 1	$$3.52 \mathrm{ms} \pm 15.9 \mathrm{μs}\left({\color{gray}-0.895 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: medium, policies: 108	$$4.07 \mathrm{ms} \pm 20.7 \mathrm{μs}\left({\color{gray}-0.763 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 133	$$4.33 \mathrm{ms} \pm 33.3 \mathrm{μs}\left({\color{gray}-0.861 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$3.46 \mathrm{ms} \pm 19.7 \mathrm{μs}\left({\color{gray}-0.450 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 63	$$4.01 \mathrm{ms} \pm 24.6 \mathrm{μs}\left({\color{gray}-0.855 \mathrm{\%}}\right) $$	Flame Graph

policy_resolution_none

Function	Value	Mean	Flame graphs
resolve_policies_for_actor	user: empty, selectivity: high, policies: 2	$$2.68 \mathrm{ms} \pm 16.6 \mathrm{μs}\left({\color{gray}3.28 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$2.53 \mathrm{ms} \pm 12.9 \mathrm{μs}\left({\color{gray}0.190 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 2	$$2.66 \mathrm{ms} \pm 15.0 \mathrm{μs}\left({\color{gray}2.51 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 8	$$2.98 \mathrm{ms} \pm 20.8 \mathrm{μs}\left({\color{gray}4.31 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$2.76 \mathrm{ms} \pm 15.6 \mathrm{μs}\left({\color{gray}4.03 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 3	$$2.95 \mathrm{ms} \pm 18.7 \mathrm{μs}\left({\color{gray}3.12 \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 23.3 \mathrm{μs}\left({\color{gray}0.705 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$2.74 \mathrm{ms} \pm 16.1 \mathrm{μs}\left({\color{gray}-2.001 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 26	$$2.91 \mathrm{ms} \pm 14.2 \mathrm{μs}\left({\color{gray}-4.005 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: high, policies: 94	$$3.42 \mathrm{ms} \pm 26.1 \mathrm{μs}\left({\color{gray}-1.106 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: low, policies: 1	$$2.99 \mathrm{ms} \pm 14.6 \mathrm{μs}\left({\color{gray}-1.180 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: medium, policies: 27	$$3.21 \mathrm{ms} \pm 13.6 \mathrm{μs}\left({\color{gray}-3.857 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 66	$$3.34 \mathrm{ms} \pm 23.2 \mathrm{μs}\left({\color{gray}-0.041 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$2.94 \mathrm{ms} \pm 14.4 \mathrm{μs}\left({\color{gray}-1.085 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 29	$$3.24 \mathrm{ms} \pm 20.8 \mathrm{μs}\left({\color{gray}-1.315 \mathrm{\%}}\right) $$	Flame Graph

read_scaling_complete

Function	Value	Mean	Flame graphs
entity_by_id;one_depth	1 entities	$$41.5 \mathrm{ms} \pm 237 \mathrm{μs}\left({\color{gray}0.500 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	10 entities	$$32.4 \mathrm{ms} \pm 190 \mathrm{μs}\left({\color{gray}-1.797 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	25 entities	$$35.5 \mathrm{ms} \pm 199 \mathrm{μs}\left({\color{gray}-0.268 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	5 entities	$$31.4 \mathrm{ms} \pm 205 \mathrm{μs}\left({\color{gray}0.184 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	50 entities	$$41.8 \mathrm{ms} \pm 301 \mathrm{μs}\left({\color{gray}-0.630 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	1 entities	$$48.6 \mathrm{ms} \pm 245 \mathrm{μs}\left({\color{gray}-1.254 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	10 entities	$$38.8 \mathrm{ms} \pm 215 \mathrm{μs}\left({\color{lightgreen}-6.015 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	25 entities	$$89.8 \mathrm{ms} \pm 625 \mathrm{μs}\left({\color{gray}0.955 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	5 entities	$$33.1 \mathrm{ms} \pm 185 \mathrm{μs}\left({\color{gray}-1.450 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	50 entities	$$302 \mathrm{ms} \pm 1.13 \mathrm{ms}\left({\color{red}16.0 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	1 entities	$$10.3 \mathrm{ms} \pm 59.6 \mathrm{μs}\left({\color{gray}-2.793 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	10 entities	$$10.4 \mathrm{ms} \pm 80.2 \mathrm{μs}\left({\color{gray}-1.136 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	25 entities	$$10.5 \mathrm{ms} \pm 72.2 \mathrm{μs}\left({\color{gray}-0.311 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	5 entities	$$10.2 \mathrm{ms} \pm 58.6 \mathrm{μs}\left({\color{gray}-2.704 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	50 entities	$$10.4 \mathrm{ms} \pm 73.6 \mathrm{μs}\left({\color{gray}-1.174 \mathrm{\%}}\right) $$	Flame Graph

read_scaling_linkless

Function	Value	Mean	Flame graphs
entity_by_id	1 entities	$$10.3 \mathrm{ms} \pm 58.5 \mathrm{μs}\left({\color{gray}-0.522 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10 entities	$$10.3 \mathrm{ms} \pm 58.1 \mathrm{μs}\left({\color{gray}-1.884 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	100 entities	$$10.4 \mathrm{ms} \pm 55.0 \mathrm{μs}\left({\color{gray}-1.540 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1000 entities	$$10.2 \mathrm{ms} \pm 74.9 \mathrm{μs}\left({\color{gray}-1.670 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10000 entities	$$10.6 \mathrm{ms} \pm 50.9 \mathrm{μs}\left({\color{gray}-2.715 \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.7 \mathrm{ms} \pm 79.5 \mathrm{μs}\left({\color{gray}0.240 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/book/v/1	$$10.6 \mathrm{ms} \pm 60.1 \mathrm{μs}\left({\color{gray}-3.252 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/building/v/1	$$10.6 \mathrm{ms} \pm 65.6 \mathrm{μs}\left({\color{gray}-3.270 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/organization/v/1	$$10.8 \mathrm{ms} \pm 85.4 \mathrm{μs}\left({\color{gray}1.04 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/page/v/2	$$10.9 \mathrm{ms} \pm 80.2 \mathrm{μs}\left({\color{gray}0.773 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/person/v/1	$$10.6 \mathrm{ms} \pm 58.6 \mathrm{μs}\left({\color{gray}-2.805 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/playlist/v/1	$$10.7 \mathrm{ms} \pm 77.6 \mathrm{μs}\left({\color{gray}-0.269 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/song/v/1	$$11.1 \mathrm{ms} \pm 164 \mathrm{μs}\left({\color{gray}3.44 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/uk-address/v/1	$$10.7 \mathrm{ms} \pm 72.6 \mathrm{μs}\left({\color{gray}-0.605 \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.37 \mathrm{ms} \pm 82.4 \mathrm{μs}\left({\color{gray}4.92 \mathrm{\%}}\right) $$	Flame Graph

representative_read_multiple_entities

Function	Value	Mean	Flame graphs
entity_by_property	traversal_paths=0	0	$$58.0 \mathrm{ms} \pm 537 \mathrm{μs}\left({\color{gray}4.37 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=255	1,resolve_depths=inherit:1;values:255;properties:255;links:127;link_dests:126;type:true	$$111 \mathrm{ms} \pm 952 \mathrm{μs}\left({\color{gray}3.33 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:0;links:0;link_dests:0;type:false	$$62.8 \mathrm{ms} \pm 555 \mathrm{μs}\left({\color{gray}0.658 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:0;links:1;link_dests:0;type:true	$$72.5 \mathrm{ms} \pm 630 \mathrm{μs}\left({\color{gray}1.14 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:2;links:1;link_dests:0;type:true	$$83.3 \mathrm{ms} \pm 682 \mathrm{μs}\left({\color{gray}2.55 \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.5 \mathrm{ms} \pm 575 \mathrm{μs}\left({\color{gray}-0.318 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=0	0	$$49.0 \mathrm{ms} \pm 395 \mathrm{μs}\left({\color{red}10.8 \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	$$71.5 \mathrm{ms} \pm 509 \mathrm{μs}\left({\color{gray}-2.546 \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	$$51.8 \mathrm{ms} \pm 437 \mathrm{μs}\left({\color{gray}1.11 \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	$$61.5 \mathrm{ms} \pm 558 \mathrm{μs}\left({\color{gray}2.65 \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.2 \mathrm{ms} \pm 467 \mathrm{μs}\left({\color{gray}-3.956 \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	$$60.1 \mathrm{ms} \pm 420 \mathrm{μs}\left({\color{gray}-3.951 \mathrm{\%}}\right) $$

scenarios

Function	Value	Mean	Flame graphs
full_test	query-limited	$$119 \mathrm{ms} \pm 657 \mathrm{μs}\left({\color{gray}2.57 \mathrm{\%}}\right) $$	Flame Graph
full_test	query-unlimited	$$131 \mathrm{ms} \pm 533 \mathrm{μs}\left({\color{gray}2.28 \mathrm{\%}}\right) $$	Flame Graph
linked_queries	query-limited	$$17.2 \mathrm{ms} \pm 97.4 \mathrm{μs}\left({\color{lightgreen}-22.756 \mathrm{\%}}\right) $$	Flame Graph
linked_queries	query-unlimited	$$559 \mathrm{ms} \pm 1.13 \mathrm{ms}\left({\color{red}7.36 \mathrm{\%}}\right) $$	Flame Graph