BE-590: hgraph: Refactor entity query handlers into entity/query submodule

[indietyp]

🌟 What is the purpose of this PR?

The entity query request types and their associated HTTP handler functions have been refactored out of a single flat module into a dedicated entity/query submodule hierarchy. As part of this, the old entity_query_request.rs file — which contained a large amount of dead code related to a planned HashQL integration, proxy deserialization structs, and a four-variant subgraph enum — has been removed entirely.

The new QueryEntitiesRequest and QueryEntitySubgraphRequest types are simpler: QueryEntitiesRequest is now a plain struct with a filter field directly (no EntityQuery enum wrapping a filter or raw HashQL value), and QueryEntitySubgraphRequest is a two-variant untagged enum (Paths / ResolveDepths) rather than four variants. The into_params and into_traversal_params methods are now on the request types themselves rather than on a separate EntityQueryOptions struct, removing an intermediate layer.

The Interactive header parameter has also been removed from the query_entities and query_entity_subgraph OpenAPI path definitions, as it was only relevant to the HashQL compilation path that no longer exists in these handlers.

🔗 Related links

• https://linear.app/hash/issue/BE-537/hashql-remove-old-backend-wire-up-hashql-in-the-api

🔍 What does this change?

• Converts entity.rs into entity/mod.rs and extracts query handlers into entity/query/mod.rs and request types into entity/query/request.rs.
• Removes entity_query_request.rs and all dead code it contained: EntityQuery, EntityQueryOptions, FlatQueryEntitiesRequestData, CompilationOptions, HashQL diagnostic rendering, and the four-variant QueryEntitySubgraphRequest.
• Replaces the EntityQuery::Filter / EntityQuery::Query split with a direct filter: Filter<'q, Entity> field on QueryEntitiesRequest.
• Moves into_params and into_traversal_params onto QueryEntitiesRequest and QueryEntitySubgraphRequest respectively, eliminating EntityQueryOptions as a separate type.
• Removes the Interactive header from query_entities and query_entity_subgraph handler signatures and OpenAPI docs.
• Updates benchmark code in tests/graph/benches to use the simplified request types directly, removing the into_parts / from_parts round-trips that previously extracted an EntityQuery and EntityQueryOptions.
• Adds unit tests in entity/query/request.rs covering deserialization of both request types, including required-field validation and correct disambiguation of the Paths vs ResolveDepths subgraph variants.

🛡 What tests cover this?

• New unit tests in libs/@local/graph/api/src/rest/entity/query/request.rs covering minimal and fully-populated QueryEntitiesRequest deserialization, rejection of missing required fields, and correct parsing of both QueryEntitySubgraphRequest variants including edge cases around ontology vs entity traversal edges.

❓ How to test this?

1. Checkout the branch.
2. Run cargo test in libs/@local/graph/api.
3. Exercise the /entities/query, /entities/query/subgraph, and /entities/query/count endpoints and confirm they behave as before.

[cursor]

PR Summary

Medium Risk
This changes the public REST/OpenAPI contract for entity query endpoints (required filter, no query or Interactive header), which can break clients still sending HashQL or the old request shape.

Overview
Entity query HTTP handlers and request types move from a flat entity module into entity/query, and the old entity_query_request.rs layer is removed.

API contract: QueryEntitiesRequest is now a single struct with a required filter field instead of a filter vs raw query (HashQL) union. EntityQueryOptions is folded into that struct; subgraph requests use a two-variant Paths / ResolveDepths enum that composes the same base request via flatten. OpenAPI drops EntityQueryOptions, the Interactive header on query/subgraph routes, and the four-way subgraph oneOf shapes in favor of the simpler schema.

Runtime: Handlers no longer prime a HashQL heap, compile queries, or honor Interactive for diagnostic rendering—requests deserialize to Filter and go straight to into_params / into_traversal_params. Benchmarks and tests are updated for the new types, with new deserialization tests for required fields and subgraph variant disambiguation.

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	Jun 23, 2026 10:01am
petrinaut	Ready	Preview	Jun 23, 2026 10:01am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Jun 23, 2026 10:01am

[indietyp]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• BE-614: HashQL: Generate synthetic closure bodies for intrinsics used as first-class values #8895
• BE-615: HashQL: Introduce the concept of synthetic closures in the MIR #8894
• BE-607: HashQL: Refactor ModuleRegistry into builder/immutable split with allocator-generic stdlib construction #8887
• BE-538: HashQL: Permission system integration #8882
• BE-71: HashQL: Consolidate AST special-form expansion stages into one #8870
• BE-481: HashQL: Reify null and empty tuple as unit constants #8853
• BE-537, BE-537: hgraph: REST /hashql endpoint with E2E tests #8827
• BE-592: HashQL: Remove old eval graph path and core value types #8841
• BE-590: hgraph: Refactor entity query handlers into entity/query submodule #8840 👈 (View in Graphite)
• BE-587, BE-588: HashQL: Introduce CodeGenerationContext/CodeExecutionContext split and eval-stage Interner #8839
• BE-581, BE-589: HashQL: Introduce pass::lower/pass::place pipeline facades and fix cached constructor closure bug #8838
• BE-585, BE-591: HashQL: Add MIR interpreter test suite and refactor diagnostic categories #8837
• BE-583, BE-584, BE-586: HashQL: Add HeapPool, improve spans, and propagate Critical severity through diagnostics #8836
• BE-582: HashQL: Change opaque types from invariant to covariant #8835
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 59.58%. Comparing base (a5659a4) to head (57dccbf).

Additional details and impacted files

@@                                    Coverage Diff                                    @@
##           bm/be-587-hashql-eval-interner-and-context-restructuring    #8840   +/-   ##
=========================================================================================
  Coverage                                                     59.58%   59.58%           
=========================================================================================
  Files                                                          1349     1349           
  Lines                                                        131875   131875           
  Branches                                                       5946     5946           
=========================================================================================
  Hits                                                          78574    78574           
  Misses                                                        52393    52393           
  Partials                                                        908      908           

Flag	Coverage Δ
apps.hash-ai-worker-ts	1.39% <ø> (ø)
local.hash-backend-utils	2.82% <ø> (ø)
local.hash-graph-sdk	9.63% <ø> (ø)
local.hash-isomorphic-utils	0.00% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Refactors the entity query REST API by moving query request types and handlers into a dedicated rest/entity/query submodule, while removing the legacy entity_query_request.rs module (including dead/unused HashQL-related code paths). This simplifies the request shapes (direct filter struct field; two-variant subgraph request) and updates benchmarks accordingly.

Changes:

• Extracts entity query handlers to libs/@local/graph/api/src/rest/entity/query/mod.rs and request types (plus deserialization tests) to .../entity/query/request.rs.
• Removes libs/@local/graph/api/src/rest/entity_query_request.rs and the Interactive header from entity query OpenAPI definitions/handlers.
• Updates manual benchmark scaffolding to use the new request types and APIs directly.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/graph/benches/manual_queries/entity_queries/mod.rs	Updates benchmarks to use the refactored request types and the new into_*params APIs.
libs/@local/graph/api/src/rest/mod.rs	Drops the old entity_query_request module inclusion.
libs/@local/graph/api/src/rest/entity/query/request.rs	Introduces simplified request types and adds unit tests for deserialization/variant disambiguation.
libs/@local/graph/api/src/rest/entity/query/mod.rs	Adds extracted handlers and updated OpenAPI path definitions without the Interactive header.
libs/@local/graph/api/src/rest/entity/mod.rs	Wires the new submodule into routing and OpenAPI, removing the inlined legacy handlers/types.
libs/@local/graph/api/src/rest/entity_query_request.rs	Removes the legacy request module (dead HashQL/proxy-related code).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8a4c804. Configure here.}

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

libs/@local/graph/api/src/rest/entity/mod.rs:4

• This refactor moves QueryEntitiesRequest / QueryEntitySubgraphRequest under entity::query, but the previous public re-exports from hash_graph_api::rest::entity::* are gone. Since hash-graph-api is a published crate, this is a breaking Rust API change for downstream users even though HTTP behavior is unchanged.

Consider re-exporting the request/error types from entity to preserve the old import path (or add a deprecation cycle if you want to force the new path).