Skip to content

Conversation

@indietyp
Copy link
Member

@indietyp indietyp commented Jan 8, 2026

🌟 What is the purpose of this PR?

Add MIR interpreter for executing HashQL code at runtime. This implements a stack-based interpreter that can execute MIR code, handle function calls, and manipulate runtime values.

🔍 What does this change?

  • Adds a complete MIR interpreter implementation in libs/@local/hashql/mir/src/interpret/
  • Implements runtime value representation with support for primitives, aggregates, and collections
  • Adds error handling and diagnostic reporting for runtime errors
  • Implements a call stack for function execution and tracking
  • Adds support for binary and unary operations, control flow, and function calls
  • Enhances the newtype! macro to support custom display formatting
  • Adds reserve method to InternSet for preallocating capacity
  • Updates ID display formatting for better readability in error messages

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 test suite for the interpreter covering basic execution, operations, control flow, function calls, and error handling
  • Tests for value representation and manipulation

❓ How to test this?

  1. Run the test suite with cargo test -p hashql-mir
  2. Run Miri tests with cargo miri test -p hashql-mir

@cursor
Copy link

cursor bot commented Jan 8, 2026

PR Summary

Adds a full MIR interpreter capable of executing MIR with function calls, control flow, operand/aggregate evaluation, and rich runtime diagnostics.

  • Introduces interpret/ (runtime, call stack, locals/place handling, value ops, error-to-diagnostic conversion)
  • Extends Int with bitwise ops and robust negation; supports ~ unary op via op!
  • Enhances id::newtype! with #[display = ..] and #[no_display]; updates display of BasicBlockId (bb{}), Local (%{}), Location, and place indexing
  • Adds InternSet::reserve() and reserves capacity in type environment prefill
  • Adds entity schema fixtures for organization and person
  • Updates dependencies (adds imbl; bumps itertools in prost) and adjusts miri test target

Written by Cursor Bugbot for commit 85204ae. This will update automatically on new commits. Configure here.

@github-actions github-actions bot added area/deps Relates to third-party dependencies (area) area/libs Relates to first-party libraries/crates/packages (area) type/eng > backend Owned by the @backend team labels Jan 8, 2026
This was referenced Jan 8, 2026
Copy link
Member Author

indietyp commented Jan 8, 2026

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

@augmentcode
Copy link

augmentcode bot commented Jan 8, 2026

🤖 Augment PR Summary

Summary: Adds a stack-based MIR interpreter to execute HashQL MIR at runtime, alongside a runtime Value model and rich diagnostics.

Changes:

  • Introduce interpret/ with Runtime, CallStack, per-frame Locals, and stepping over statements/terminators
  • Add runtime Value types (primitives, aggregates, collections) with total ordering/equality; collections backed by imbl
  • Add RuntimeError + InterpretDiagnosticCategory and conversion to diagnostics with callstack labeling
  • Implement additional ops: unary ~, plus bitwise/unary operator traits for MIR Int
  • Enhance ID display via newtype! display controls and update MIR pretty-printers/analysis output accordingly
  • Add InternSet::reserve and pre-reserve environment kinds; update dev scripts and deps

Technical Notes: Includes extensive end-to-end tests (and Miri coverage) for execution, control flow, calls/returns, aggregates, inputs, and error/ICE paths.

🤖 Was this summary useful? React with 👍 or 👎

Copy link

@augmentcode augmentcode bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review completed. 3 suggestions posted.

Fix All in Augment

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

@codspeed-hq
Copy link

codspeed-hq bot commented Jan 8, 2026

Merging this PR will not alter performance

✅ 18 untouched benchmarks
🗄️ 12 archived benchmarks run1


Comparing bm/be-257-hashql-implement-interpreter (85204ae) with main (b51cad9)

Open in CodSpeed

Footnotes

  1. 12 benchmarks were run, but are now archived. If they were deleted in another branch, consider rebasing to remove them from the report. Instead if they were added back, click here to restore them.

@indietyp indietyp force-pushed the bm/be-257-hashql-implement-interpreter branch from e304b49 to 85204ae Compare January 19, 2026 11:05
@graphite-app graphite-app bot changed the base branch from graphite-base/8245 to main January 19, 2026 11:06
@graphite-app
Copy link
Contributor

graphite-app bot commented Jan 19, 2026

Merge activity

  • Jan 19, 11:06 AM UTC: Graphite rebased this pull request, because this pull request is set to merge when ready.
  • Jan 19, 11:06 AM UTC: Graphite rebased this pull request, because this pull request is set to merge when ready.

@indietyp indietyp added this pull request to the merge queue Jan 19, 2026
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to failed status checks Jan 19, 2026
@github-actions
Copy link
Contributor

Benchmark results

@rust/hash-graph-benches – Integrations

policy_resolution_large

Function Value Mean Flame graphs
resolve_policies_for_actor user: empty, selectivity: high, policies: 2002 $$26.3 \mathrm{ms} \pm 128 \mathrm{μs}\left({\color{gray}0.749 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: low, policies: 1 $$3.25 \mathrm{ms} \pm 21.5 \mathrm{μs}\left({\color{gray}0.456 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: medium, policies: 1001 $$12.1 \mathrm{ms} \pm 79.6 \mathrm{μs}\left({\color{gray}2.92 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: high, policies: 3314 $$41.8 \mathrm{ms} \pm 278 \mathrm{μs}\left({\color{gray}0.002 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: low, policies: 1 $$13.9 \mathrm{ms} \pm 78.5 \mathrm{μs}\left({\color{gray}2.24 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: medium, policies: 1526 $$23.6 \mathrm{ms} \pm 175 \mathrm{μs}\left({\color{gray}4.27 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: high, policies: 2078 $$26.5 \mathrm{ms} \pm 304 \mathrm{μs}\left({\color{lightgreen}-36.866 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: low, policies: 1 $$3.63 \mathrm{ms} \pm 29.2 \mathrm{μs}\left({\color{lightgreen}-81.584 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: medium, policies: 1033 $$11.1 \mathrm{ms} \pm 70.0 \mathrm{μs}\left({\color{lightgreen}-62.478 \mathrm{\%}}\right) $$ Flame Graph

policy_resolution_medium

Function Value Mean Flame graphs
resolve_policies_for_actor user: empty, selectivity: high, policies: 102 $$3.68 \mathrm{ms} \pm 17.8 \mathrm{μs}\left({\color{gray}3.23 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: low, policies: 1 $$2.84 \mathrm{ms} \pm 11.9 \mathrm{μs}\left({\color{gray}1.80 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: medium, policies: 51 $$3.22 \mathrm{ms} \pm 17.4 \mathrm{μs}\left({\color{gray}3.37 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: high, policies: 269 $$4.98 \mathrm{ms} \pm 23.4 \mathrm{μs}\left({\color{gray}1.30 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: low, policies: 1 $$3.44 \mathrm{ms} \pm 26.0 \mathrm{μs}\left({\color{gray}3.07 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: medium, policies: 107 $$3.95 \mathrm{ms} \pm 16.4 \mathrm{μs}\left({\color{gray}1.97 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: high, policies: 133 $$4.23 \mathrm{ms} \pm 27.8 \mathrm{μs}\left({\color{gray}3.93 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: low, policies: 1 $$3.29 \mathrm{ms} \pm 12.6 \mathrm{μs}\left({\color{gray}3.05 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: medium, policies: 63 $$3.88 \mathrm{ms} \pm 20.4 \mathrm{μs}\left({\color{gray}1.58 \mathrm{\%}}\right) $$ Flame Graph

policy_resolution_none

Function Value Mean Flame graphs
resolve_policies_for_actor user: empty, selectivity: high, policies: 2 $$2.57 \mathrm{ms} \pm 13.5 \mathrm{μs}\left({\color{red}9.82 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: low, policies: 1 $$2.48 \mathrm{ms} \pm 9.51 \mathrm{μs}\left({\color{red}8.11 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: medium, policies: 1 $$2.61 \mathrm{ms} \pm 14.6 \mathrm{μs}\left({\color{red}9.01 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: high, policies: 8 $$2.75 \mathrm{ms} \pm 10.2 \mathrm{μs}\left({\color{red}5.64 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: low, policies: 1 $$2.65 \mathrm{ms} \pm 9.31 \mathrm{μs}\left({\color{red}7.63 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: medium, policies: 3 $$2.87 \mathrm{ms} \pm 12.2 \mathrm{μs}\left({\color{red}8.21 \mathrm{\%}}\right) $$ Flame Graph

policy_resolution_small

Function Value Mean Flame graphs
resolve_policies_for_actor user: empty, selectivity: high, policies: 52 $$2.92 \mathrm{ms} \pm 16.2 \mathrm{μs}\left({\color{red}7.58 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: low, policies: 1 $$2.60 \mathrm{ms} \pm 10.6 \mathrm{μs}\left({\color{red}9.66 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: medium, policies: 25 $$2.75 \mathrm{ms} \pm 11.7 \mathrm{μs}\left({\color{red}7.51 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: high, policies: 94 $$3.26 \mathrm{ms} \pm 16.3 \mathrm{μs}\left({\color{red}7.11 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: low, policies: 1 $$2.84 \mathrm{ms} \pm 13.6 \mathrm{μs}\left({\color{red}8.77 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: medium, policies: 26 $$3.05 \mathrm{ms} \pm 13.6 \mathrm{μs}\left({\color{red}7.49 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: high, policies: 66 $$3.15 \mathrm{ms} \pm 18.2 \mathrm{μs}\left({\color{red}6.29 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: low, policies: 1 $$2.79 \mathrm{ms} \pm 15.6 \mathrm{μs}\left({\color{red}7.99 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: medium, policies: 29 $$3.07 \mathrm{ms} \pm 21.0 \mathrm{μs}\left({\color{red}8.60 \mathrm{\%}}\right) $$ Flame Graph

read_scaling_complete

Function Value Mean Flame graphs
entity_by_id;one_depth 1 entities $$39.3 \mathrm{ms} \pm 150 \mathrm{μs}\left({\color{gray}2.36 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;one_depth 10 entities $$76.0 \mathrm{ms} \pm 501 \mathrm{μs}\left({\color{gray}1.70 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;one_depth 25 entities $$43.2 \mathrm{ms} \pm 231 \mathrm{μs}\left({\color{gray}4.37 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;one_depth 5 entities $$46.2 \mathrm{ms} \pm 214 \mathrm{μs}\left({\color{gray}4.24 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;one_depth 50 entities $$53.2 \mathrm{ms} \pm 257 \mathrm{μs}\left({\color{gray}3.13 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;two_depth 1 entities $$39.8 \mathrm{ms} \pm 167 \mathrm{μs}\left({\color{gray}-0.192 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;two_depth 10 entities $$417 \mathrm{ms} \pm 959 \mathrm{μs}\left({\color{gray}1.20 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;two_depth 25 entities $$93.6 \mathrm{ms} \pm 402 \mathrm{μs}\left({\color{red}7.49 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;two_depth 5 entities $$84.0 \mathrm{ms} \pm 408 \mathrm{μs}\left({\color{gray}1.89 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;two_depth 50 entities $$309 \mathrm{ms} \pm 911 \mathrm{μs}\left({\color{red}11.7 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;zero_depth 1 entities $$14.4 \mathrm{ms} \pm 62.3 \mathrm{μs}\left({\color{gray}0.539 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;zero_depth 10 entities $$14.8 \mathrm{ms} \pm 63.8 \mathrm{μs}\left({\color{gray}2.36 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;zero_depth 25 entities $$15.0 \mathrm{ms} \pm 67.0 \mathrm{μs}\left({\color{gray}2.59 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;zero_depth 5 entities $$15.3 \mathrm{ms} \pm 87.1 \mathrm{μs}\left({\color{gray}4.93 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;zero_depth 50 entities $$17.7 \mathrm{ms} \pm 79.8 \mathrm{μs}\left({\color{gray}0.287 \mathrm{\%}}\right) $$ Flame Graph

read_scaling_linkless

Function Value Mean Flame graphs
entity_by_id 1 entities $$14.4 \mathrm{ms} \pm 58.1 \mathrm{μs}\left({\color{gray}0.679 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id 10 entities $$14.5 \mathrm{ms} \pm 56.0 \mathrm{μs}\left({\color{gray}1.40 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id 100 entities $$14.4 \mathrm{ms} \pm 62.6 \mathrm{μs}\left({\color{gray}1.45 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id 1000 entities $$15.4 \mathrm{ms} \pm 72.9 \mathrm{μs}\left({\color{gray}3.29 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id 10000 entities $$22.4 \mathrm{ms} \pm 138 \mathrm{μs}\left({\color{gray}2.82 \mathrm{\%}}\right) $$ Flame Graph

representative_read_entity

Function Value Mean Flame graphs
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/block/v/1 $$29.8 \mathrm{ms} \pm 286 \mathrm{μs}\left({\color{gray}2.46 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/book/v/1 $$31.3 \mathrm{ms} \pm 327 \mathrm{μs}\left({\color{red}7.93 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/building/v/1 $$29.5 \mathrm{ms} \pm 279 \mathrm{μs}\left({\color{gray}2.14 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/organization/v/1 $$29.0 \mathrm{ms} \pm 253 \mathrm{μs}\left({\color{gray}1.10 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/page/v/2 $$29.8 \mathrm{ms} \pm 290 \mathrm{μs}\left({\color{red}6.16 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/person/v/1 $$30.0 \mathrm{ms} \pm 273 \mathrm{μs}\left({\color{gray}2.95 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/playlist/v/1 $$29.7 \mathrm{ms} \pm 290 \mathrm{μs}\left({\color{gray}3.02 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/song/v/1 $$29.5 \mathrm{ms} \pm 253 \mathrm{μs}\left({\color{gray}2.64 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/uk-address/v/1 $$30.3 \mathrm{ms} \pm 249 \mathrm{μs}\left({\color{gray}4.57 \mathrm{\%}}\right) $$ Flame Graph

representative_read_entity_type

Function Value Mean Flame graphs
get_entity_type_by_id Account ID: bf5a9ef5-dc3b-43cf-a291-6210c0321eba $$8.05 \mathrm{ms} \pm 32.5 \mathrm{μs}\left({\color{gray}1.87 \mathrm{\%}}\right) $$ Flame Graph

representative_read_multiple_entities

Function Value Mean Flame graphs
entity_by_property traversal_paths=0 0 $$47.1 \mathrm{ms} \pm 177 \mathrm{μs}\left({\color{red}6.36 \mathrm{\%}}\right) $$
entity_by_property traversal_paths=255 1,resolve_depths=inherit:1;values:255;properties:255;links:127;link_dests:126;type:true $$96.2 \mathrm{ms} \pm 471 \mathrm{μs}\left({\color{red}5.46 \mathrm{\%}}\right) $$
entity_by_property traversal_paths=2 1,resolve_depths=inherit:0;values:0;properties:0;links:0;link_dests:0;type:false $$53.6 \mathrm{ms} \pm 262 \mathrm{μs}\left({\color{red}7.73 \mathrm{\%}}\right) $$
entity_by_property traversal_paths=2 1,resolve_depths=inherit:0;values:0;properties:0;links:1;link_dests:0;type:true $$62.4 \mathrm{ms} \pm 273 \mathrm{μs}\left({\color{red}7.43 \mathrm{\%}}\right) $$
entity_by_property traversal_paths=2 1,resolve_depths=inherit:0;values:0;properties:2;links:1;link_dests:0;type:true $$70.1 \mathrm{ms} \pm 346 \mathrm{μs}\left({\color{red}5.26 \mathrm{\%}}\right) $$
entity_by_property traversal_paths=2 1,resolve_depths=inherit:0;values:2;properties:2;links:1;link_dests:0;type:true $$75.8 \mathrm{ms} \pm 332 \mathrm{μs}\left({\color{gray}4.94 \mathrm{\%}}\right) $$
link_by_source_by_property traversal_paths=0 0 $$51.2 \mathrm{ms} \pm 324 \mathrm{μs}\left({\color{red}7.32 \mathrm{\%}}\right) $$
link_by_source_by_property traversal_paths=255 1,resolve_depths=inherit:1;values:255;properties:255;links:127;link_dests:126;type:true $$77.9 \mathrm{ms} \pm 306 \mathrm{μs}\left({\color{gray}4.55 \mathrm{\%}}\right) $$
link_by_source_by_property traversal_paths=2 1,resolve_depths=inherit:0;values:0;properties:0;links:0;link_dests:0;type:false $$57.5 \mathrm{ms} \pm 283 \mathrm{μs}\left({\color{red}5.65 \mathrm{\%}}\right) $$
link_by_source_by_property traversal_paths=2 1,resolve_depths=inherit:0;values:0;properties:0;links:1;link_dests:0;type:true $$65.2 \mathrm{ms} \pm 308 \mathrm{μs}\left({\color{gray}4.76 \mathrm{\%}}\right) $$
link_by_source_by_property traversal_paths=2 1,resolve_depths=inherit:0;values:0;properties:2;links:1;link_dests:0;type:true $$66.8 \mathrm{ms} \pm 325 \mathrm{μs}\left({\color{gray}4.17 \mathrm{\%}}\right) $$
link_by_source_by_property traversal_paths=2 1,resolve_depths=inherit:0;values:2;properties:2;links:1;link_dests:0;type:true $$67.2 \mathrm{ms} \pm 296 \mathrm{μs}\left({\color{gray}4.20 \mathrm{\%}}\right) $$

scenarios

Function Value Mean Flame graphs
full_test query-limited $$135 \mathrm{ms} \pm 522 \mathrm{μs}\left({\color{gray}-1.582 \mathrm{\%}}\right) $$ Flame Graph
full_test query-unlimited $$136 \mathrm{ms} \pm 642 \mathrm{μs}\left({\color{gray}-1.567 \mathrm{\%}}\right) $$ Flame Graph
linked_queries query-limited $$39.5 \mathrm{ms} \pm 194 \mathrm{μs}\left({\color{gray}-2.414 \mathrm{\%}}\right) $$ Flame Graph
linked_queries query-unlimited $$561 \mathrm{ms} \pm 1.00 \mathrm{ms}\left({\color{gray}-3.513 \mathrm{\%}}\right) $$ Flame Graph

@indietyp indietyp added this pull request to the merge queue Jan 19, 2026
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to failed status checks Jan 19, 2026
@indietyp indietyp added this pull request to the merge queue Jan 19, 2026
Merged via the queue into main with commit 94ee310 Jan 19, 2026
186 of 202 checks passed
@indietyp indietyp deleted the bm/be-257-hashql-implement-interpreter branch January 19, 2026 14:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/apps > hash* Affects HASH (a `hash-*` app) area/apps area/deps Relates to third-party dependencies (area) area/libs Relates to first-party libraries/crates/packages (area) type/eng > backend Owned by the @backend team

Development

Successfully merging this pull request may close these issues.

3 participants