BE-494: HashQL: Loop-breaker selection for recursive inlining

[indietyp]

🌟 What is the purpose of this PR?

This PR implements a three-color depth-first search algorithm for directed graphs and integrates it with a loop-breaker selection system for the MIR inliner. The three-color DFS enables cycle detection and postorder traversal, while the loop-breaker system allows the inliner to handle mutually recursive functions by strategically selecting which functions to avoid inlining within strongly connected components (SCCs).

🔗 Related links

• Related to MIR optimization and inlining strategies for recursive function groups

🔍 What does this change?

• Adds a new three-color depth-first search implementation in libs/@local/hashql/core/src/graph/algorithms/color/mod.rs with support for cycle detection and visitor callbacks
• Implements a loop-breaker selection algorithm in libs/@local/hashql/mir/src/pass/transform/inline/loop_breaker.rs that uses scoring heuristics to choose which functions in recursive SCCs should not be inlined
• Extends the inline pass to process SCCs with loop-breaker awareness, allowing inlining of non-breaker functions while avoiding infinite recursion
• Adds comprehensive test coverage for both the three-color DFS algorithm and loop-breaker selection
• Updates the call graph analysis to support querying callers of a function
• Adds iterator support for SCC members with both immutable and mutable access
• Changes unary NOT operator representation from ! to ~ in MIR output formatting
• Extends inline configuration with InlineLoopBreakerConfig for tuning breaker selection heuristics

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

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

📜 Does this require a change to the docs?

The changes in this PR:

• are internal and do not require a docs change

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

The changes in this PR:

• do not affect the execution graph

🛡 What tests cover this?

• Comprehensive unit tests for three-color DFS including cycle detection, postorder traversal, edge filtering, and state accumulation
• Loop-breaker selection tests covering mutual recursion, cost-based selection, multi-cycle SCCs, and ordering verification
• Integration tests showing the complete inlining behavior with loop breakers
• Existing MIR transformation tests updated to reflect the new unary operator formatting

❓ How to test this?

1. Run the test suite to verify all three-color DFS and loop-breaker functionality
2. Test with mutually recursive MIR functions to confirm proper breaker selection and inlining behavior
3. Verify that the inliner no longer gets stuck in infinite loops when processing recursive function groups

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	May 11, 2026 11:11am
petrinaut	Ready	Preview	May 11, 2026 11:11am

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
hashdotdesign	Ignored	Preview	May 11, 2026 11:11am
hashdotdesign-tokens	Ignored	Preview	May 11, 2026 11:11am

[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-513: HashQL: Rework dynamic aggregate size estimation #8697
• BE-512: HashQL: Allow cross-backend transitions for SwitchInt terminators #8696
• BE-524: HashQL: Remove island schedule module #8694
• BE-525: HashQL: Remove implicit type-widening from Integer operations, and make comparison size aware #8693
• BE-515: HashQL: Remove OFFSET 0 materialization fence from generated query #8650
• BE-514: HashQL: implement iterative adjustment passes in placement solver #8635
• BE-500, BE-501: HashQL: Unify mixed parameter resolution in data dependency analysis #8607
• BE-494: HashQL: Loop-breaker selection for recursive inlining #8600 👈 (View in Graphite)
• BE-482: HashQL: Remove logical not from MIR and fix postgres boolean lowering #8595
• BE-474: HashQL: Take into account terminator target eligibility in execution backend placement #8587
• BE-455: HashQL: Introduce evaluation orchestrator #8586
• BE-523: HashQL: Suspendable interpreter with structured values and input system #8675
• BE-522: HashQL: Expand stdlib type system with temporal types #8674
• BE-306: HashQL: PostgreSQL translation #8526
• BE-457: HashQL: MIR execution pipeline extensions for postgres compilation #8525
• BE-456: HashQL: Entity type model enrichment and graph store query extensions #8524
• BE-429: HashQL: Add island dependency graph with data requirement resolution #8501
• BE-428: HashQL: Simplify traversal tracking to path recording #8498
• BE-434: HashQL: Refactor entity storage path resolution with centralized schema mapping #8496
• BE-427: Add hashql-macros crate with procedural macros for ID types and symbols #8495
• main

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

[codecov]

Codecov Report

❌ Patch coverage is 90.28213% with 62 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.79%. Comparing base (256f483) to head (ac41f3d).

Files with missing lines	Patch %	Lines
...cal/hashql/core/src/graph/algorithms/tarjan/mod.rs	0.00%	22 Missing ⚠️
...shql/mir/src/pass/transform/inline/loop_breaker.rs	90.00%	9 Missing and 4 partials ⚠️
...ocal/hashql/mir/src/pass/transform/inline/tests.rs	94.62%	9 Missing and 4 partials ⚠️
...ocal/hashql/core/src/graph/algorithms/color/mod.rs	93.24%	5 Missing ⚠️
...al/hashql/core/src/graph/algorithms/color/tests.rs	96.21%	4 Missing and 1 partial ⚠️
...@local/hashql/mir/src/pass/transform/inline/mod.rs	89.65%	1 Missing and 2 partials ⚠️
...local/hashql/mir/src/pass/transform/inline/find.rs	0.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@                                     Coverage Diff                                      @@
##           bm/be-482-hashql-remove-logical-not-from-unary-operators    #8600      +/-   ##
============================================================================================
+ Coverage                                                     63.61%   68.79%   +5.17%     
============================================================================================
  Files                                                          1274      946     -328     
  Lines                                                        137848    92967   -44881     
  Branches                                                       5519     4704     -815     
============================================================================================
- Hits                                                          87688    63952   -23736     
+ Misses                                                        49249    28370   -20879     
+ Partials                                                        911      645     -266     

Flag	Coverage Δ
apps.hash-ai-worker-ts	1.41% <ø> (ø)
apps.hash-api	0.00% <ø> (ø)
blockprotocol.type-system	?
local.claude-hooks	?
local.harpc-client	?
local.hash-backend-utils	2.81% <ø> (ø)
local.hash-graph-sdk	9.63% <ø> (ø)
local.hash-isomorphic-utils	0.00% <ø> (ø)
rust.antsi	?
rust.error-stack	?
rust.harpc-codec	?
rust.harpc-net	?
rust.harpc-tower	?
rust.harpc-types	?
rust.harpc-wire-protocol	?
rust.hash-codec	?
rust.hash-graph-api	2.52% <ø> (ø)
rust.hash-graph-authorization	?
rust.hash-graph-postgres-store	?
rust.hash-graph-store	?
rust.hash-graph-temporal-versioning	?
rust.hash-graph-types	?
rust.hash-graph-validation	?
rust.hashql-ast	87.23% <ø> (ø)
rust.hashql-compiletest	28.26% <ø> (ø)
rust.hashql-core	82.25% <85.96%> (+0.03%)	⬆️
rust.hashql-eval	79.71% <ø> (ø)
rust.hashql-hir	89.06% <ø> (ø)
rust.hashql-mir	91.68% <92.68%> (+0.01%)	⬆️
rust.hashql-syntax-jexpr	94.06% <ø> (ø)

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

☔ View full report in Codecov by Sentry.
📢 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.

[codspeed-hq]

Merging this PR will not alter performance

✅ 80 untouched benchmarks

---

_{Comparing bm/be-494-hashql-scc-loop-breaker-inlining (ac41f3d) with bm/be-482-hashql-remove-logical-not-from-unary-operators (256f483)}

[vercel]

Deployment failed with the following error:

Invalid request: `attribution.gitUser` should NOT have additional property `isBot`.

[cursor]

PR Summary

High Risk
Changes core MIR inlining behavior for recursive call graphs by introducing loop-breaker selection and new SCC ordering, which can affect codegen size/perf and correctness around recursion. Also adds new graph algorithms and unsafe slice iteration in Tarjan members that could introduce subtle traversal bugs if incorrect.

Overview
Adds a new color graph algorithm module implementing an iterative three-color DFS (TriColorDepthFirstSearch + TriColorVisitor) with cycle detection and postorder callbacks, and re-exports it via graph::algorithms.

Extends Tarjan SCC member handling with Members::{iter, iter_mut} and IntoIterator support (including an unsafe mutable-slice iterator), and adds a CallGraph::callers() API for incoming-edge queries.

Updates the MIR inliner to support recursive SCCs via loop-breaker selection (InlineLoopBreakerConfig + new loop_breaker module): it scores SCC members, greedily marks breakers until the remainder is acyclic (checked via three-color DFS), reorders SCC members for processing, and changes both normal and aggressive inlining to inline within SCCs except when targeting breakers (and to always skip self-calls). Comprehensive new unit/UI tests cover DFS behavior, breaker selection, ordering, and filter aggressive inlining interactions.

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

[augmentcode]

🤖 Augment PR Summary

Summary: Adds loop-breaker-aware inlining for mutually recursive HashQL MIR functions, enabling safe inlining within recursive SCCs without infinite expansion.

Changes:

• Introduces an iterative three-color DFS utility (with cycle detection and postorder callbacks) in hashql_core::graph::algorithms::color.
• Adds loop-breaker selection (loop_breaker.rs) that scores SCC members and greedily picks a feedback-vertex set to break recursion.
• Reorders SCC members so non-breakers are processed in postorder of the breaker-removed DAG, followed by breakers, improving within-SCC optimization ordering.
• Extends the MIR inliner to inline within SCCs except for self-calls and calls targeting loop breakers.
• Enhances call graph analysis with a callers(def) iterator and SCC member iteration helpers.
• Updates MIR formatting/tests to render unary NOT as ~ (instead of !) and refreshes snapshots.
• Adds substantial unit/integration tests covering breaker selection, multi-breaker SCCs, ordering, and aggressive filter behavior.

Technical Notes: Breaker selection uses repeated cycle checks over the remaining subgraph (filtered via DFS edge ignoring) to ensure the non-breaker remainder is acyclic before allowing within-SCC inlining.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

[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 4ea12a3. Configure here.}