Skip to content

BE-1132: Define the run interface for orchestration backends - #10410

Open
thehabbos007 wants to merge 9 commits into
asa/be-958-orchestration-run-modelfrom
asa/be-1132-orchestration-run-interface
Open

thehabbos007 wants to merge 9 commits into
asa/be-958-orchestration-run-modelfrom
asa/be-1132-orchestration-run-interface

Conversation

@thehabbos007

Copy link
Copy Markdown
Contributor

🌟 Purpose

Adds the run interface that integrations are written against and that backends implement, so the DBOS backend (BE-960) can start on it. Stacked on #10402.

🔍 Changes

  • RunFunction is pinned to a FunctionVersion and requests its steps through StepContext::run(name, step). Steps are FnMut like DBOS's, since a retry calls them again.
  • A failed step returns a Report<StepFailure>. Its messages go to the logs, and only the failure is recorded.
  • Runs starts, reads and cancels runs without a worker. Starting the same RunId again attaches to it, and a second run under an active admission key gets StartError::AlreadyActive.
  • Worker executes runs of its function's version until it's shut down, and CoordinationStore is the TypeScript runner's token bucket for the Graph rate limit.

The doc comments state what each backend has to guarantee.

⚠️ Known issues

  • Nothing implements the traits yet. BE-1133 adds the in-memory implementation.

@thehabbos007 thehabbos007 self-assigned this Nov 9, 2026
@vercel

vercel Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
hash Ready Ready Preview Nov 10, 2026 2:00pm UTC
petrinaut Ready Ready Preview Nov 10, 2026 2:00pm UTC
petrinaut-docs Ready Ready Preview Nov 10, 2026 2:00pm UTC
1 Skipped Deployment
Project Deployment Actions Updated
hashdotdesign-tokens Ignored Ignored Preview Nov 10, 2026 2:00pm UTC

Request Review

@github-actions github-actions Bot added area/deps Relates to third-party dependencies (area) area/infra Relates to version control, CI, CD or IaC (area) area/libs Relates to first-party libraries/crates/packages (area) type/eng > backend Owned by the @backend team area/apps > hash-integrations labels Nov 9, 2026
@thehabbos007
thehabbos007 added this pull request to stack #10414 November 9, 2026 14:23
@codecov

codecov Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.76%. Comparing base (22eba25) to head (da9fb17).

Additional details and impacted files
@@                          Coverage Diff                           @@
##           asa/be-958-orchestration-run-model   #10410      +/-   ##
======================================================================
- Coverage                               68.76%   68.76%   -0.01%     
======================================================================
  Files                                    2090     2090              
  Lines                                  214238   214232       -6     
  Branches                                 9315     9315              
======================================================================
- Hits                                   147312   147306       -6     
  Misses                                  65055    65055              
  Partials                                 1871     1871              
Flag Coverage Δ
hash-integrations-orchestration 97.33% <100.00%> (-0.06%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 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

codspeed Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

Merging this PR will not alter performance

2 warnings, 1 note

⚠️ Unable to measure the execution of 6 benchmarks

These benchmarks measured no execution time, so their results are not comparable and count as unchanged. This usually happens when the compiler removes the code under test.

Prevent compiler optimizations

See affected benchmarks

⚠️ 2 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

ℹ️ 6 benchmarks have no flamegraph

The flamegraph wasn't generated: no execution data was recorded while the benchmark ran. Make sure the compiler didn't optimize the benchmark out.

See affected benchmarks

✅ 98 untouched benchmarks


Comparing asa/be-1132-orchestration-run-interface (da9fb17) with asa/be-958-orchestration-run-model (22eba25)

Open in CodSpeed

@github-actions

Copy link
Copy Markdown
Contributor

Benchmark results

hash-graph-benches – Integrations

policy_resolution_large

Function Value Mean Flame graphs
resolve_policies_for_actor user: empty, selectivity: high, policies: 2002 $$28.0 \mathrm{ms} \pm 242 \mathrm{μs}\left({\color{gray}-0.691 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: low, policies: 1 $$3.04 \mathrm{ms} \pm 22.9 \mathrm{μs}\left({\color{gray}-1.382 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: medium, policies: 1002 $$12.9 \mathrm{ms} \pm 142 \mathrm{μs}\left({\color{gray}1.03 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: high, policies: 3314 $$96.1 \mathrm{ms} \pm 1.51 \mathrm{ms}\left({\color{gray}-2.039 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: low, policies: 1 $$13.3 \mathrm{ms} \pm 165 \mathrm{μs}\left({\color{gray}1.18 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: medium, policies: 1527 $$23.1 \mathrm{ms} \pm 279 \mathrm{μs}\left({\color{gray}-0.045 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: high, policies: 2078 $$28.8 \mathrm{ms} \pm 297 \mathrm{μs}\left({\color{gray}-2.336 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: low, policies: 1 $$3.30 \mathrm{ms} \pm 28.4 \mathrm{μs}\left({\color{gray}-1.190 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: medium, policies: 1033 $$13.9 \mathrm{ms} \pm 157 \mathrm{μs}\left({\color{gray}0.246 \mathrm{\%}}\right) $$ Flame Graph

policy_resolution_medium

Function Value Mean Flame graphs
resolve_policies_for_actor user: empty, selectivity: high, policies: 102 $$3.49 \mathrm{ms} \pm 36.8 \mathrm{μs}\left({\color{gray}1.58 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: low, policies: 1 $$2.59 \mathrm{ms} \pm 20.1 \mathrm{μs}\left({\color{gray}1.43 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: medium, policies: 52 $$2.95 \mathrm{ms} \pm 27.5 \mathrm{μs}\left({\color{gray}-0.040 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: high, policies: 269 $$4.80 \mathrm{ms} \pm 52.4 \mathrm{μs}\left({\color{gray}-0.140 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: low, policies: 1 $$3.06 \mathrm{ms} \pm 21.0 \mathrm{μs}\left({\color{gray}0.249 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: medium, policies: 108 $$3.76 \mathrm{ms} \pm 39.9 \mathrm{μs}\left({\color{gray}1.36 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: high, policies: 133 $$3.99 \mathrm{ms} \pm 35.1 \mathrm{μs}\left({\color{gray}-4.422 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: low, policies: 1 $$3.07 \mathrm{ms} \pm 30.3 \mathrm{μs}\left({\color{gray}-1.666 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: medium, policies: 63 $$3.65 \mathrm{ms} \pm 32.9 \mathrm{μs}\left({\color{gray}-4.018 \mathrm{\%}}\right) $$ Flame Graph

policy_resolution_none

Function Value Mean Flame graphs
resolve_policies_for_actor user: empty, selectivity: high, policies: 2 $$2.28 \mathrm{ms} \pm 17.1 \mathrm{μs}\left({\color{gray}0.595 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: low, policies: 1 $$2.21 \mathrm{ms} \pm 17.9 \mathrm{μs}\left({\color{gray}4.05 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: medium, policies: 2 $$2.34 \mathrm{ms} \pm 20.3 \mathrm{μs}\left({\color{gray}3.82 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: high, policies: 8 $$2.51 \mathrm{ms} \pm 22.2 \mathrm{μs}\left({\color{gray}0.589 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: low, policies: 1 $$2.30 \mathrm{ms} \pm 13.9 \mathrm{μs}\left({\color{gray}-1.019 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: medium, policies: 3 $$2.54 \mathrm{ms} \pm 19.2 \mathrm{μs}\left({\color{gray}1.92 \mathrm{\%}}\right) $$ Flame Graph

policy_resolution_small

Function Value Mean Flame graphs
resolve_policies_for_actor user: empty, selectivity: high, policies: 52 $$2.68 \mathrm{ms} \pm 25.3 \mathrm{μs}\left({\color{gray}-0.215 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: low, policies: 1 $$2.42 \mathrm{ms} \pm 20.3 \mathrm{μs}\left({\color{gray}-1.591 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: empty, selectivity: medium, policies: 26 $$2.56 \mathrm{ms} \pm 21.6 \mathrm{μs}\left({\color{gray}-0.128 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: high, policies: 94 $$3.00 \mathrm{ms} \pm 25.6 \mathrm{μs}\left({\color{lightgreen}-7.770 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: low, policies: 1 $$2.67 \mathrm{ms} \pm 28.3 \mathrm{μs}\left({\color{gray}0.695 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: seeded, selectivity: medium, policies: 27 $$2.86 \mathrm{ms} \pm 26.4 \mathrm{μs}\left({\color{gray}-1.948 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: high, policies: 66 $$2.97 \mathrm{ms} \pm 26.2 \mathrm{μs}\left({\color{gray}1.59 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: low, policies: 1 $$2.55 \mathrm{ms} \pm 17.2 \mathrm{μs}\left({\color{gray}-1.675 \mathrm{\%}}\right) $$ Flame Graph
resolve_policies_for_actor user: system, selectivity: medium, policies: 29 $$2.82 \mathrm{ms} \pm 21.9 \mathrm{μs}\left({\color{gray}-2.096 \mathrm{\%}}\right) $$ Flame Graph

read_scaling_complete

Function Value Mean Flame graphs
entity_by_id;one_depth 1 entities $$38.4 \mathrm{ms} \pm 298 \mathrm{μs}\left({\color{gray}-2.458 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;one_depth 10 entities $$29.0 \mathrm{ms} \pm 196 \mathrm{μs}\left({\color{lightgreen}-5.346 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;one_depth 25 entities $$32.6 \mathrm{ms} \pm 268 \mathrm{μs}\left({\color{gray}-2.858 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;one_depth 5 entities $$35.1 \mathrm{ms} \pm 1.45 \mathrm{ms}\left({\color{red}21.9 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;one_depth 50 entities $$41.9 \mathrm{ms} \pm 313 \mathrm{μs}\left({\color{gray}3.14 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;two_depth 1 entities $$46.1 \mathrm{ms} \pm 310 \mathrm{μs}\left({\color{gray}-3.008 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;two_depth 10 entities $$37.6 \mathrm{ms} \pm 255 \mathrm{μs}\left({\color{gray}-0.042 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;two_depth 25 entities $$108 \mathrm{ms} \pm 688 \mathrm{μs}\left({\color{gray}2.64 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;two_depth 5 entities $$51.4 \mathrm{ms} \pm 4.97 \mathrm{ms}\left({\color{red}67.6 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;two_depth 50 entities $$348 \mathrm{ms} \pm 1.30 \mathrm{ms}\left({\color{lightgreen}-10.095 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;zero_depth 1 entities $$9.80 \mathrm{ms} \pm 63.5 \mathrm{μs}\left({\color{gray}3.66 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;zero_depth 10 entities $$9.73 \mathrm{ms} \pm 66.3 \mathrm{μs}\left({\color{gray}2.20 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;zero_depth 25 entities $$9.59 \mathrm{ms} \pm 68.1 \mathrm{μs}\left({\color{gray}-3.239 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;zero_depth 5 entities $$9.61 \mathrm{ms} \pm 64.8 \mathrm{μs}\left({\color{gray}0.137 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id;zero_depth 50 entities $$9.64 \mathrm{ms} \pm 70.1 \mathrm{μs}\left({\color{gray}-0.563 \mathrm{\%}}\right) $$ Flame Graph

read_scaling_linkless

Function Value Mean Flame graphs
entity_by_id 1 entities $$9.50 \mathrm{ms} \pm 68.5 \mathrm{μs}\left({\color{gray}-1.017 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id 10 entities $$9.51 \mathrm{ms} \pm 65.4 \mathrm{μs}\left({\color{gray}-0.025 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id 100 entities $$9.68 \mathrm{ms} \pm 60.6 \mathrm{μs}\left({\color{gray}2.05 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id 1000 entities $$10.0 \mathrm{ms} \pm 68.2 \mathrm{μs}\left({\color{gray}2.76 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id 10000 entities $$10.3 \mathrm{ms} \pm 80.1 \mathrm{μs}\left({\color{gray}3.15 \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 $$10.0 \mathrm{ms} \pm 93.4 \mathrm{μs}\left({\color{gray}-0.434 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/book/v/1 $$9.92 \mathrm{ms} \pm 66.8 \mathrm{μs}\left({\color{gray}-1.466 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/building/v/1 $$9.97 \mathrm{ms} \pm 73.4 \mathrm{μs}\left({\color{gray}-0.809 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/organization/v/1 $$9.92 \mathrm{ms} \pm 76.7 \mathrm{μs}\left({\color{gray}-1.492 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/page/v/2 $$9.87 \mathrm{ms} \pm 62.7 \mathrm{μs}\left({\color{gray}-2.398 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/person/v/1 $$10.1 \mathrm{ms} \pm 89.1 \mathrm{μs}\left({\color{gray}-0.449 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/playlist/v/1 $$9.83 \mathrm{ms} \pm 60.7 \mathrm{μs}\left({\color{gray}-1.329 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/song/v/1 $$9.88 \mathrm{ms} \pm 74.5 \mathrm{μs}\left({\color{gray}-1.835 \mathrm{\%}}\right) $$ Flame Graph
entity_by_id entity type ID: https://blockprotocol.org/@alice/types/entity-type/uk-address/v/1 $$9.76 \mathrm{ms} \pm 59.5 \mathrm{μs}\left({\color{gray}-1.429 \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 $$7.21 \mathrm{ms} \pm 52.5 \mathrm{μs}\left({\color{gray}0.801 \mathrm{\%}}\right) $$ Flame Graph

representative_read_multiple_entities

Function Value Mean Flame graphs
entity_by_property traversal_paths=0 0 $$53.1 \mathrm{ms} \pm 427 \mathrm{μs}\left({\color{gray}0.468 \mathrm{\%}}\right) $$
entity_by_property traversal_paths=255 1,resolve_depths=inherit:1;values:255;properties:255;links:127;link_dests:126;type:true $$98.9 \mathrm{ms} \pm 551 \mathrm{μs}\left({\color{gray}-1.210 \mathrm{\%}}\right) $$
entity_by_property traversal_paths=2 1,resolve_depths=inherit:0;values:0;properties:0;links:0;link_dests:0;type:false $$60.0 \mathrm{ms} \pm 382 \mathrm{μs}\left({\color{gray}-0.179 \mathrm{\%}}\right) $$
entity_by_property traversal_paths=2 1,resolve_depths=inherit:0;values:0;properties:0;links:1;link_dests:0;type:true $$68.8 \mathrm{ms} \pm 501 \mathrm{μs}\left({\color{gray}-0.989 \mathrm{\%}}\right) $$
entity_by_property traversal_paths=2 1,resolve_depths=inherit:0;values:0;properties:2;links:1;link_dests:0;type:true $$75.2 \mathrm{ms} \pm 452 \mathrm{μs}\left({\color{gray}-2.073 \mathrm{\%}}\right) $$
entity_by_property traversal_paths=2 1,resolve_depths=inherit:0;values:2;properties:2;links:1;link_dests:0;type:true $$81.5 \mathrm{ms} \pm 647 \mathrm{μs}\left({\color{gray}0.019 \mathrm{\%}}\right) $$
link_by_source_by_property traversal_paths=0 0 $$41.4 \mathrm{ms} \pm 282 \mathrm{μs}\left({\color{gray}0.133 \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 $$67.0 \mathrm{ms} \pm 519 \mathrm{μs}\left({\color{gray}0.035 \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 $$47.1 \mathrm{ms} \pm 329 \mathrm{μs}\left({\color{gray}-1.231 \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 $$55.4 \mathrm{ms} \pm 366 \mathrm{μs}\left({\color{gray}-1.401 \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 $$57.2 \mathrm{ms} \pm 389 \mathrm{μs}\left({\color{gray}-1.423 \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 $$57.9 \mathrm{ms} \pm 483 \mathrm{μs}\left({\color{gray}-0.264 \mathrm{\%}}\right) $$

scenarios

Function Value Mean Flame graphs
full_test query-limited $$113 \mathrm{ms} \pm 942 \mathrm{μs}\left({\color{gray}-1.875 \mathrm{\%}}\right) $$ Flame Graph
full_test query-unlimited $$123 \mathrm{ms} \pm 915 \mathrm{μs}\left({\color{gray}-0.284 \mathrm{\%}}\right) $$ Flame Graph
linked_queries query-limited $$17.5 \mathrm{ms} \pm 146 \mathrm{μs}\left({\color{gray}-0.112 \mathrm{\%}}\right) $$ Flame Graph
linked_queries query-unlimited $$489 \mathrm{ms} \pm 1.38 \mathrm{ms}\left({\color{gray}3.97 \mathrm{\%}}\right) $$ Flame Graph

@thehabbos007
thehabbos007 marked this pull request as ready for review November 11, 2026 15:53
@thehabbos007
thehabbos007 requested review from a team as code owners November 11, 2026 15:53
Copilot AI balanced review requested due to automatic review settings November 11, 2026 15:53
@veria-ai

veria-ai Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

PR overview

No security issues were found in this pull request.

Reviews

@cursor

cursor Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

PR Summary

Low Risk
Interface-only additions in a library crate with no runtime behavior or security-sensitive logic implemented yet.

Overview
Introduces the public API integrations and orchestration backends must share: RunFunction / StepContext for deterministic step execution, and Runs / Worker for starting, inspecting, canceling, and executing runs (including idempotent RunId attach and admission-key StartError::AlreadyActive).

Adds CoordinationStore with TokenBucket consumption for cross-process Graph rate limiting, plus new validated name types RunId and BucketScope (via a shared name_type! macro). StepFailure is now a proper error context for logged step failures, and tokio-util supplies shutdown CancellationToken on Worker::work.

Docs in lib.rs and README.md spell out the three backend traits; no trait implementations land in this PR.

Reviewed by Cursor Bugbot for commit da9fb17. Bugbot is set up for automated code reviews on this repo. Configure here.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟢 Approval recommended

No active review issues are reported for the backend-neutral orchestration interfaces.

No open issues 🎉

What changed in this PR

Defines the backend-neutral run interface for integration orchestration, building on the run model from #10402 and preparing for the DBOS backend. Backend implementations remain follow-up work.

Changes:

  • Adds version-pinned run functions and replay-aware, retryable step execution contracts.
  • Defines worker execution and run lifecycle APIs, including idempotent starts and admission-key conflicts.
  • Introduces shared token-bucket coordination and documents backend guarantees.
File Description
libs/​@local/​integrations/​orchestration/​src/​runs.rs Defines run lifecycle, status, errors, and worker interfaces.
libs/​@local/​integrations/​orchestration/​src/​run.rs Defines run functions, step execution, and run errors.
libs/​@local/​integrations/​orchestration/​src/​name.rs Consolidates validated name types; adds run IDs and bucket scopes.
libs/​@local/​integrations/​orchestration/​src/​lib.rs Exports the new interfaces and documents their roles.
libs/​@local/​integrations/​orchestration/​src/​event.rs Makes step failures usable as error-report contexts.
libs/​@local/​integrations/​orchestration/​src/​coordination.rs Defines shared token-bucket configuration and consumption.
libs/​@local/​integrations/​orchestration/​README.md Documents backend responsibilities and interface relationships.
libs/​@local/​integrations/​orchestration/​Cargo.toml Adds the public tokio-util dependency for cancellation.
Cargo.lock Records the orchestration crate’s added dependency.

Review effort: Balanced

@thehabbos007
thehabbos007 requested review from a team as code owners November 16, 2026 12:42

This branch was successfully deployed

4 active deployments
Preview – hash — da9fb175 Deployed Nov 10, 2026 by vercel[bot]
Preview – petrinaut — da9fb175 Deployed Nov 10, 2026 by vercel[bot]
Preview – petrinaut-docs — da9fb175 Deployed Nov 10, 2026 by vercel[bot]
pull-request — da9fb175 Deployed Nov 10, 2026 by thehabbos007 via Sourcemaps (@apps/hash-ai-worker-ts) #44124
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/apps > hash-integrations area/deps Relates to third-party dependencies (area) area/infra Relates to version control, CI, CD or IaC (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.

4 participants