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 15, 2026 7:57am
petrinaut	Ready	Preview	May 15, 2026 7:57am

2 Skipped Deployments

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

[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 92.68293% with 30 lines in your changes missing coverage. Please review.
✅ Project coverage is 63.35%. Comparing base (c6685d5) to head (4e7a72a).

Files with missing lines	Patch %	Lines
...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 ⚠️
...@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                                                     62.88%   63.35%   +0.47%     
============================================================================================
  Files                                                          1379     1385       +6     
  Lines                                                        141785   144511    +2726     
  Branches                                                       5844     5912      +68     
============================================================================================
+ Hits                                                          89156    91551    +2395     
- Misses                                                        51695    51990     +295     
- Partials                                                        934      970      +36     

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-eval	79.71% <ø> (ø)
rust.hashql-hir	89.06% <ø> (ø)
rust.hashql-mir	91.68% <92.68%> (-0.43%)	⬇️
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

✅ 24 untouched benchmarks
⏩ 56 skipped benchmarks¹

---

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

Footnotes

1. 56 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on bm/be-482-hashql-remove-logical-not-from-unary-operators (5738ec8) during the generation of this report, so 8aa1a5b was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[vercel]

Deployment failed with the following error:

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

[cursor]

PR Summary

Medium Risk
Changes the MIR inlining algorithm for recursive SCCs by introducing loop-breaker selection and new cycle-detection traversal, which can affect optimization output and termination behavior across many functions.

Overview
Adds a new color graph algorithm module implementing iterative three-color DFS (TriColorDepthFirstSearch/TriColorVisitor) with cycle detection, postorder finishing, edge filtering, and state accumulation, and re-exports it from graph::algorithms.

Integrates loop-breaker selection into the MIR inliner: computes SCC members, scores SCC functions, greedily selects breaker functions to make the SCC remainder acyclic, reorders SCC members (non-breakers in postorder, breakers last), and updates both normal and aggressive inlining to inline within SCCs except when targeting a selected breaker (and to skip self-calls).

Extends supporting APIs (CallGraph::callers, tarjan::Members::{iter,iter_mut,IntoIterator}) and adds substantial unit/UI test coverage plus new snapshot outputs for recursive inlining/loop-breaker behavior.

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