BE-514: HashQL: implement iterative adjustment passes in placement solver

[indietyp]

🌟 What is the purpose of this PR?

This PR enhances the placement solver in the MIR dataflow analysis framework by implementing iterative adjustment passes that alternate direction until convergence. Instead of a simple two-pass approach (forward then backward), the solver now continues refining assignments in alternating directions until no further improvements are found, converging to a better local minimum.

🔍 What does this change?

• Adds a reverse() method to the Direction enum to toggle between Forward and Backward directions
• Replaces the single backward refinement pass with iterative adjustment passes that alternate direction until convergence
• Modifies adjust_trivial() and adjust_cyclic() methods to return boolean flags indicating whether assignments changed
• Introduces a new run_adjustment() method that processes regions in the specified direction and tracks changes
• Updates documentation to reflect the new iterative convergence approach rather than the previous two-pass strategy

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?

• Existing placement solver tests continue to validate the functionality
• Updated test in backward_pass_keeps_assignment_when_csp_fails() to handle the new return signature

❓ How to test this?

1. Checkout the branch
2. Run the existing MIR placement solver tests
3. Confirm that placement optimization still works correctly with the new iterative approach

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	May 28, 2026 1:35pm
petrinaut	Ready	Preview	May 28, 2026 1:35pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
hashdotdesign	Ignored	Preview	May 28, 2026 1:35pm
hashdotdesign-tokens	Ignored	Preview	May 28, 2026 1:35pm

[indietyp]

• BE-537: Remove old filter API backend and wire up HashQL in the API #8827
• 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 👈 (View in Graphite)
• BE-500, BE-501: HashQL: Unify mixed parameter resolution in data dependency analysis #8607
• BE-494: HashQL: Loop-breaker selection for recursive inlining #8600
• 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.

[indietyp]

remind me to add a test case for the reason this fails before merging:

3-node chain A → B → C:

 - Unary costs: u_A(0)=3, u_A(1)=0; u_B(0)=u_B(1)=0; u_C(0)=0
 - Edge costs: A–B mismatch cost 2, B–C mismatch cost 1
 - Start from labeling 000

Backward sweep (sinks first): C stays 0, B stays 0 (given A=0, C=0), A switches to 1 (given B=0). Final: 1,0,0.

But changing only B from 0 to 1 lowers total cost — so the result after one sweep is not a 1-opt local minimum.

[codecov]

Codecov Report

❌ Patch coverage is 91.78082% with 24 lines in your changes missing coverage. Please review.
✅ Project coverage is 59.10%. Comparing base (a8da2f8) to head (798b079).
⚠️ Report is 14 commits behind head on main.

Files with missing lines	Patch %	Lines
...shql/mir/src/pass/transform/inline/loop_breaker.rs	90.00%	9 Missing and 4 partials ⚠️
...l/mir/src/pass/analysis/data_dependency/resolve.rs	93.33%	1 Missing and 3 partials ⚠️
...@local/hashql/mir/src/pass/transform/inline/mod.rs	89.65%	1 Missing and 2 partials ⚠️
...hashql/mir/src/pass/transform/inst_simplify/mod.rs	0.00%	2 Missing ⚠️
...shql/mir/src/pass/execution/placement/solve/mod.rs	97.87%	1 Missing ⚠️
...local/hashql/mir/src/pass/transform/inline/find.rs	0.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8635      +/-   ##
==========================================
+ Coverage   59.04%   59.10%   +0.05%     
==========================================
  Files        1341     1342       +1     
  Lines      129387   129587     +200     
  Branches     5837     5851      +14     
==========================================
+ Hits        76398    76587     +189     
- Misses      52088    52096       +8     
- Partials      901      904       +3     

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-compiletest	28.26% <ø> (ø)
rust.hashql-eval	75.69% <ø> (ø)
rust.hashql-mir	86.84% <91.78%> (+0.09%)	⬆️

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-514-hashql-solver-iterate-forwardbackward-passes-to-convergence (798b079) with bm/be-500-hashql-forward-substitution-unified-param-resolution (a6a0edb)²}

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-500-hashql-forward-substitution-unified-param-resolution (53acbb7) during the generation of this report, so 266df53 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[cursor]

PR Summary

Medium Risk
Changes how execution targets are chosen across the MIR placement pass; incorrect convergence or cost-mode wiring could shift runtime placement without obvious compile errors.

Overview
Replaces the placement solver’s single backward refinement pass with iterative adjustment passes that walk regions in alternating directions (backward, forward, …) until no region assignment changes, aiming for a better local minimum with fuller boundary context.

Adds Direction::reverse() for the dataflow framework and a new run_adjustment path that drives trivial and cyclic re-evaluation via adjust_trivial / adjust_cyclic, which now report whether anything changed. Cyclic solving gains ConstraintSatisfactionMode (Initial vs Adjustment), mapping to CostEstimationConfig::LOOP during forward/initial CSP work and TRIVIAL during adjustments; forward pass and rewind still use Initial mode.

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

[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 211c141. Configure here.}

[augmentcode]

🤖 Augment PR Summary

Summary: Enhances the HashQL MIR placement solver by iterating adjustment passes (alternating direction) until assignments stop improving, instead of doing a single backward refinement.

Changes:

• Added Direction::reverse() to toggle between forward and backward traversal.
• Introduced ConstraintSatisfactionMode to switch CSP cost-estimation weighting between initial solving and later adjustments.
• Updated PlacementSolver::run_in to run the forward pass once, then repeat adjustment passes (backward/forward/…) until a pass makes no assignment changes.
• Refactored adjust_trivial / adjust_cyclic to return whether they changed assignments, and used this to drive convergence.
• Updated CSP/solver tests for the new constructor signature and return values.

Technical Notes: Adjustment solving for cyclic regions now evaluates candidates with full boundary weighting (via TRIVIAL) and threads this choice through CSP cost estimation via the new mode.

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

[augmentcode]

Review completed. 1 suggestion posted.

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