BE-523: HashQL: Suspendable interpreter with structured values and input system

[indietyp]

🌟 What is the purpose of this PR?

Rework the MIR interpreter to support suspend/resume execution, richer value representations, and a proper input system. Together these let the interpreter pause when it needs external data (e.g. a database query), hand back a structured description of what it needs, and resume once the caller provides the result.

🔍 What does this change?

Suspension model (interpret/suspension/)

• Introduce a suspend/resume protocol: when the interpreter hits a GraphRead terminator it yields a Suspension instead of blocking. Callers drive a start/resume loop until they get a Return.
• GraphReadSuspension extracts temporal axes, filter parameters, and entity type from the suspended state.
• Continuation carries the response value that resumes execution.
• TemporalAxesInterval / Timestamp give structured representations of the temporal query window.
• Runtime::run convenience wrapper for callers that can fulfill suspensions synchronously.

Input system (interpret/inputs.rs)

• Add Inputs<'heap, A>: a typed map from interned symbols to Values, consulted for InputOp::Load and InputOp::Exists. Replaces the unstructured FastHashMap previously threaded through the runtime. Supports both global and custom allocators.

Value representation (interpret/value/)

• Int: carry bit-width (1-bit boolean vs 128-bit integer) so serialization can distinguish true/false from 0/1 without external type info. Arithmetic promotes to 128-bit; bitwise boolean ops preserve 1-bit.
• Struct: add StructBuilder<N> for stack-allocated fixed-field construction. Enforce sorted field invariant. Add merge and project_by_name.
• Minor improvements to Opaque, List allocator parameterization, Str display.

SSA repair fix (pass/transform/ssa_repair)

• Fix block parameters not being renamed during SSA repair.
• Extend use-before-def detection to terminators, not just statements.

Entity path type resolution (pass/execution/traversal)

• Add field_path and resolve_type to EntityPath for navigating from an entity path (e.g. WebId, Properties) to its concrete stdlib type.

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

⚠️ Known issues

None

🐾 Next steps

• The orchestrator in hashql-eval consumes the suspension model and input system introduced here.

🛡 What tests cover this?

• Interpreter unit tests (interpret/tests.rs): cover the suspend/resume loop, input resolution, and value operations.
• SSA repair UI tests (tests/ui/pass/ssa_repair): cover the block parameter and terminator fixes.
• Existing pass UI tests re-blessed for snapshot changes from the Int representation change.

❓ How to test this?

1. cargo nextest run --package hashql-mir
2. cargo test --package hashql-mir --doc

[cursor]

PR Summary

High Risk
Large refactor of the core interpreter runtime and value semantics, including a new suspension protocol and changes to integer/boolean representation, which can affect execution correctness and backend integration.

Overview
Adds a suspend/resume execution model to the HashQL MIR interpreter: GraphRead terminators now yield a typed Suspension (with temporal axes extraction) and resume via Continuation, plus new Runtime::{start,resume,run_until_suspension,run_until_transition}/Yield APIs and expanded callstack/frame state to support orchestration.

Replaces the runtime’s ad-hoc input map with an Inputs container (allocator-aware) and refactors interpreter error/diagnostic plumbing to be suspension-aware (new RuntimeError generic with suspension payload, new diagnostic category, and additional type-invariant errors).

Overhauls value handling: Int now tracks bit-width to distinguish booleans from integers (updating Postgres compilation and many MIR snapshots), Opaque/Value projections now transparently traverse wrapped values, and Struct enforces sorted fields with a new stack-based StructBuilder; tests/benches are updated and expanded accordingly. Execution-pass utilities also gain small APIs (e.g. island graph lookup) and traversal paths can now resolve their stdlib TypeId.

^{Reviewed by Cursor Bugbot for commit b2d61fe. 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	Apr 29, 2026 4:00pm
petrinaut	Ready	Preview	Apr 29, 2026 4:00pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Apr 29, 2026 4:00pm

[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-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
• 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 👈 (View in Graphite)
• 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 85.71429% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 63.07%. Comparing base (deb5f19) to head (b2d61fe).

Files with missing lines	Patch %	Lines
libs/@local/hashql/eval/src/postgres/filter/mod.rs	0.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@                                 Coverage Diff                                 @@
##           bm/be-522-hashql-expand-stdlib-type-definitions    #8675      +/-   ##
===================================================================================
- Coverage                                            63.19%   63.07%   -0.12%     
===================================================================================
  Files                                                 1338     1336       -2     
  Lines                                               138468   137229    -1239     
  Branches                                              5557     5529      -28     
===================================================================================
- Hits                                                 87499    86552     -947     
+ Misses                                               50047    49767     -280     
+ Partials                                               922      910      -12     

Flag	Coverage Δ
apps.hash-ai-worker-ts	1.40% <ø> (ø)
apps.hash-api	0.00% <ø> (ø)
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	29.63% <ø> (ø)
rust.hashql-diagnostics	72.53% <100.00%> (+0.09%)	⬆️
rust.hashql-eval	81.08% <0.00%> (ø)
rust.hashql-hir	89.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-523-hashql-suspendable-interpreter-with-structured-values-and (b2d61fe) with bm/be-522-hashql-expand-stdlib-type-definitions (deb5f19)}

[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 0a89a10. Configure here.}

[augmentcode]

🤖 Augment PR Summary

Summary: This PR upgrades the HashQL MIR interpreter to support structured runtime values and a suspend/resume execution model for external data access.

Changes:

• Introduced a new Inputs map type and updated Runtime to borrow inputs rather than owning a hash map
• Added interpreter yield points via Yield, plus Suspension/Continuation types to support suspend/resume around GraphRead
• Extended runtime diagnostics/errors to model suspension-related failures and new invariant violations (unexpected value type / invalid constructor)
• Reworked Int to track bit-width (bool vs 128-bit int) so boolean provenance round-trips cleanly through serialization
• Improved value projection to transparently project into Opaque wrappers and added a StructBuilder helper for building sorted-field structs safely
• Adjusted tests/benchmarks and various MIR passes (SSA repair, inst simplification, scheduling, traversal typing) to match the new runtime/value semantics

Technical Notes: Interpreter execution can now be driven synchronously via Runtime::run (with a suspension handler) or manually via Runtime::start/Runtime::resume, enabling backends like graph/DB to fulfill requests out-of-band.

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

[augmentcode]

Review completed. 2 suggestions posted.

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

[augmentcode]

libs/@local/hashql/mir/src/pass/transform/inst_simplify/mod.rs:262: eval_bin_op uses lhs.as_int()/rhs.as_int() for comparisons, which drops the new Int size/provenance (bool vs int) and makes const-folding potentially disagree with runtime comparisons. Consider using the Int comparison impls directly so folding matches interpreter behavior.

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}