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 19, 2026 3:56pm
petrinaut	Ready	Preview	May 19, 2026 3:56pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
hashdotdesign	Ignored	Preview	May 19, 2026 3:56pm
hashdotdesign-tokens	Ignored	Preview	May 19, 2026 3:56pm

[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 63.40%. Comparing base (e23d524) to head (bac2648).

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.27%   63.40%   +0.13%     
============================================================================================
  Files                                                          1384     1387       +3     
  Lines                                                        144232   144810     +578     
  Branches                                                       5891     5919      +28     
============================================================================================
+ Hits                                                          91258    91817     +559     
- Misses                                                        52014    52022       +8     
- Partials                                                        960      971      +11     

Flag	Coverage Δ
apps.hash-ai-worker-ts	1.41% <ø> (ø)
apps.hash-api	0.00% <ø> (ø)
local.hash-backend-utils	2.81% <ø> (ø)
local.hash-graph-sdk	9.63% <ø> (ø)
local.hash-isomorphic-utils	0.00% <ø> (ø)
rust.hash-graph-api	2.52% <ø> (ø)
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 (bac2648) with bm/be-482-hashql-remove-logical-not-from-unary-operators (e23d524)}

[vercel]

Deployment failed with the following error:

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

[cursor]

PR Summary

High Risk
High risk because it changes core MIR inlining behavior for recursive SCCs and introduces new graph algorithms (cycle detection/postorder) that influence optimization order and termination.

Overview
Adds a new iterative three-color DFS (TriColorDepthFirstSearch + TriColorVisitor) to hashql_core and exports it from graph::algorithms, including unit tests for cycle detection, postorder, edge filtering, and state accumulation.

Updates Tarjan SCC Members with iter/iter_mut + IntoIterator support, and extends CallGraph with callers() to enable caller-count based heuristics.

Refactors MIR inlining to select loop breakers per non-trivial SCC (new loop_breaker module + InlineLoopBreakerConfig): breaker targets are skipped for both normal and aggressive inlining, non-breakers within the same SCC become eligible, and SCC member processing order is rewritten to traverse the breaker-removed DAG postorder then breakers. Adds extensive inline/loop-breaker tests and new UI snapshots verifying recursive/filters behavior.

^{Reviewed by Cursor Bugbot for commit bac2648. 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.}