async-graph 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f23474b45b79529d8bed62b984c0329017e85daee7521bddf070558cc1f7ff92
+  data.tar.gz: b26664dbb15b6ba75b04e8ad07ac7ea7e6c39f0d532ac24f0b2f007647f2c6e0
+SHA512:
+  metadata.gz: 64933573224dc275532309ede2a9e6a699115ae6e52a6389171249412a9b9dd2786d728ec803bf06f7d9483d910fdd5ae048e299cf0151b7857df758f9ec6ac2
+  data.tar.gz: e81029fc6bb0a4b7a14b470beb7b885dc9d5692ed77c1dde69bfa7d88580b6450279c61c77e3c4433ea54cb2360857fe3d3ad9837551c5539b7f109684940892

data/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4.4"
+          bundler-cache: true
+      - run: bundle exec rake
+      - run: bundle exec rubocop
+      - run: bash examples/run.sh

data/.github/workflows/release.yml

@@ -0,0 +1,21 @@
+name: release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  build_and_publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4.4"
+      - run: |
+          mkdir -p ~/.gem && touch ~/.gem/credentials && chmod 0600 ~/.gem/credentials
+          printf -- "---\n:rubygems_api_key: ${API_KEY}\n" > ~/.gem/credentials
+          bundle install
+          bundle exec rake push
+        env:
+          API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,7 @@
+/.bundle/
+/pkg/
+/results/*
+!/results/.gitkeep
+/.idea/workspace.xml
+/examples/*.json
+/*.gem

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--require spec_helper
+--warnings

data/.rubocop.yml

@@ -0,0 +1,98 @@
+require:
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  Exclude:
+    - "*.gemspec"
+
+Layout/LineLength:
+  Enabled: false
+
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+
+Layout/LineEndStringConcatenationIndentation:
+  Enabled: false
+
+Layout/SpaceInsideHashLiteralBraces:
+  Enabled: false
+
+Lint/EmptyBlock:
+  Exclude:
+    - "examples/**/*.rb"
+    - "spec/**/*.rb"
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Max: 12
+
+Metrics/MethodLength:
+  Enabled: false
+
+Naming/AccessorMethodName:
+  Enabled: false
+
+Naming/FileName:
+  Exclude:
+    - "lib/*-*.rb"
+
+Naming/MethodName:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Enabled: false
+
+Naming/MemoizedInstanceVariableName:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+RSpec/BeEq:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/FilePath:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/ObjectThen:
+  Enabled: false
+
+Style/RedundantStructKeywordInit:
+  Enabled: false
+
+Style/StringConcatenation:
+  Enabled: false
+
+Style/StringLiteralsInInterpolation:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/StructInheritance:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.4.4

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/README.erb

@@ -0,0 +1,51 @@
+# AsyncGraph
+
+AsyncGraph is a small Ruby runtime for graph-style workflows that suspend on external work,
+store jobs outside the graph, and resume on later passes. It supports:
+
+- single-step graph execution
+- barrier joins such as `edge %i[left right], :merge`
+- `await.call(...)` for one external job
+- `await.all(...)` for multiple parallel jobs in one node
+
+## Installation
+
+```bash
+gem install async-graph
+```
+
+## Example
+
+```ruby
+require "async_graph"
+
+graph = AsyncGraph::Graph.new do
+  node :fetch_user do |state, await|
+    user = await.call("user", :fetch_user, user_id: state[:user_id])
+    { user: user }
+  end
+
+  set_entry_point :fetch_user
+  set_finish_point :fetch_user
+end
+
+step = graph.step(state: { user_id: 7 }, node: graph.entry)
+request = step.requests.first
+
+resumed = graph.step(
+  state: step.state,
+  node: step.node,
+  resolved: { request.key => { id: 7, name: "Ada" } }
+)
+
+resumed.state
+# => { user_id: 7, user: { id: 7, name: "Ada" } }
+```
+
+## Demo
+
+The repository includes a runnable example in `examples/`:
+
+```bash
+bash examples/run.sh
+```

data/README.md

@@ -0,0 +1,51 @@
+# AsyncGraph
+
+AsyncGraph is a small Ruby runtime for graph-style workflows that suspend on external work,
+store jobs outside the graph, and resume on later passes. It supports:
+
+- single-step graph execution
+- barrier joins such as `edge %i[left right], :merge`
+- `await.call(...)` for one external job
+- `await.all(...)` for multiple parallel jobs in one node
+
+## Installation
+
+```bash
+gem install async-graph
+```
+
+## Example
+
+```ruby
+require "async_graph"
+
+graph = AsyncGraph::Graph.new do
+  node :fetch_user do |state, await|
+    user = await.call("user", :fetch_user, user_id: state[:user_id])
+    { user: user }
+  end
+
+  set_entry_point :fetch_user
+  set_finish_point :fetch_user
+end
+
+step = graph.step(state: { user_id: 7 }, node: graph.entry)
+request = step.requests.first
+
+resumed = graph.step(
+  state: step.state,
+  node: step.node,
+  resolved: { request.key => { id: 7, name: "Ada" } }
+)
+
+resumed.state
+# => { user_id: 7, user: { id: 7, name: "Ada" } }
+```
+
+## Demo
+
+The repository includes a runnable example in `examples/`:
+
+```bash
+bash examples/run.sh
+```

data/Rakefile

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "erb"
+require "fileutils"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+require_relative "lib/async_graph/version"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec]
+
+desc "CI RSpec run with reports"
+task :rspec do
+  FileUtils.mkdir_p("results")
+  RSpec::Core::RakeTask.new(:ci_spec) do |rspec|
+    rspec.rspec_opts = "--profile --color -f documentation " \
+      "-f RspecJunitFormatter --out ./results/rspec.xml"
+  end
+  Rake::Task[:ci_spec].invoke
+end
+
+desc "Update README.md from README.erb"
+task :readme do
+  template = File.read("README.erb")
+  renderer = ERB.new(template, trim_mode: "-")
+  File.write("README.md", renderer.result)
+end
+
+desc "Build and push a new version"
+task push: %i[spec readme] do
+  gem_name = "async-graph-#{AsyncGraph::VERSION}.gem"
+
+  system("gem build async-graph.gemspec") or exit 1
+  system("gem install ./#{gem_name}") or exit 1
+  system("gem push #{gem_name}") or exit 1
+  system("gem list -r async-graph") or exit 1
+end
+
+desc "Build a new version"
+task build: %i[spec readme] do
+  system("gem build async-graph.gemspec") or exit 1
+end

data/async-graph.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "lib/async_graph/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "async-graph"
+  spec.version = AsyncGraph::VERSION
+  spec.summary = "Small async graph runtime with external job scheduling"
+  spec.description = "A minimal Ruby graph runtime that suspends on external work and resumes later."
+  spec.authors = ["Author"]
+  spec.email = ["author@email.address"]
+  spec.files = Dir[
+    "{bin,examples,lib,spec}/**/*",
+    ".github/workflows/*",
+    ".gitignore",
+    ".rspec",
+    ".rubocop.yml",
+    ".ruby-version",
+    "Gemfile",
+    "Rakefile",
+    "README.erb",
+    "README.md",
+    "async-graph.gemspec"
+  ]
+  spec.require_paths = ["lib"]
+  spec.homepage = "https://rubygems.org/gems/async-graph"
+  spec.license = "MIT"
+  spec.metadata = { "source_code_uri" => "https://github.com/example/async-graph" }
+  spec.required_ruby_version = ">= #{File.read(File.join(__dir__, ".ruby-version")).strip}"
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.10"
+  spec.add_development_dependency "rspec_junit_formatter", "~> 0.5.1"
+  spec.add_development_dependency "rubocop", "~> 1.12"
+  spec.add_development_dependency "rubocop-rake", "~> 0.6.0"
+  spec.add_development_dependency "rubocop-rspec", "~> 2.14.2"
+end

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "async_graph"
+require "irb"
+
+IRB.start(__FILE__)

data/examples/app_graph.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../lib/async_graph"
+
+GRAPH = AsyncGraph::Graph.new do
+  node :split do
+  end
+
+  node :left do
+    { left_ready: true }
+  end
+
+  node :right do
+    { right_ready: true }
+  end
+
+  node :merge do |state, await|
+    results = await.all(
+      profile: [:fetch_profile, {user_id: state[:user_id]}],
+      score: [:fetch_score, {user_id: state[:user_id]}]
+    )
+
+    {
+      left: results[:profile],
+      right: results[:score],
+      message: "#{results[:profile][:name]} score=#{results[:score][:score]}"
+    }
+  end
+
+  set_entry_point :split
+  edge :split, :left, branch: :left
+  edge :split, :right, branch: :right
+  edge %i[left right], :merge
+  set_finish_point :merge
+end

data/examples/execute_jobs.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "json"
+
+Dir.chdir(__dir__)
+
+jobs = JSON.parse(File.read("jobs.json"))
+
+jobs.fetch("jobs", []).each do |job|
+  next unless job["status"] == "pending"
+
+  job["result"] =
+    case job["kind"]
+    when "fetch_profile"
+      user_id = job.dig("payload", "user_id")
+      {"id" => user_id, "name" => "Ada-#{user_id}"}
+    when "fetch_score"
+      user_id = job.dig("payload", "user_id")
+      {"score" => user_id * 10}
+    end
+
+  next unless job["result"]
+
+  job["status"] = "done"
+  puts "done #{job["job_uid"]} #{job["kind"]}"
+end
+
+File.write("jobs.json", JSON.pretty_generate(jobs) + "\n")

data/examples/graph_run.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "app_graph"
+
+def job_for(jobs, job_uid)
+  jobs.fetch("jobs", []).find { |job| job["job_uid"] == job_uid }
+end
+
+def resolved_for(token, jobs)
+  token.fetch("awaits", {}).each_with_object({}) do |(key, job_uid), memo|
+    job = job_for(jobs, job_uid)
+    memo[key] = AsyncGraph.symbolize(job["result"]) if job && job["status"] == "done"
+  end
+end
+
+def next_job_uid(jobs)
+  "job-#{jobs.fetch("jobs", []).size + 1}"
+end
+
+def queue_job(jobs, request)
+  job_uid = next_job_uid(jobs)
+  jobs["jobs"] << AsyncGraph.stringify(
+    job_uid: job_uid,
+    kind: request.kind,
+    payload: request.payload,
+    status: :pending
+  )
+  job_uid
+end
+
+def spawn_tokens(graph_uid, token, state, destinations, next_tokens)
+  if destinations.size > 1
+    fork_uid = "fork-#{graph_uid}-#{token["token_uid"]}"
+
+    destinations.each do |edge|
+      next_tokens << AsyncGraph.stringify(
+        token_uid: "#{token["token_uid"]}.#{edge.branch}",
+        node: edge.to,
+        state: state,
+        fork_uid: fork_uid,
+        branch: edge.branch,
+        from_node: token["node"],
+        awaits: {}
+      )
+    end
+
+    return nil
+  end
+
+  edge = destinations.first
+  return state if edge.to == AsyncGraph::FINISH
+
+  next_tokens << AsyncGraph.stringify(
+    token_uid: token["token_uid"],
+    node: edge.to,
+    state: state,
+    fork_uid: token["fork_uid"],
+    branch: token["branch"],
+    from_node: token["node"],
+    awaits: {}
+  )
+
+  nil
+end
+
+def process_join(graph_state, token, joins, next_tokens)
+  expects = GRAPH.join_for(token["node"])
+  bucket_key = "#{token["fork_uid"]}:#{token["node"]}"
+  bucket = joins[bucket_key] || {"join_node" => token["node"], "states" => {}}
+  bucket["states"][token["from_node"]] = token["state"]
+
+  missing = expects.map(&:to_s) - bucket["states"].keys
+  if missing.empty?
+    joins.delete(bucket_key)
+    merged_state = bucket["states"].values.reduce({}) do |memo, state|
+      memo.merge(AsyncGraph.symbolize(state))
+    end
+
+    puts "#{graph_state["graph_uid"]}/#{token["token_uid"]} joined"
+    next_tokens << AsyncGraph.stringify(
+      token_uid: "#{token["fork_uid"]}.join",
+      node: token["node"],
+      state: merged_state,
+      fork_uid: nil,
+      branch: nil,
+      from_node: nil,
+      awaits: {}
+    )
+    return nil
+  end
+
+  joins[bucket_key] = bucket
+  puts "#{graph_state["graph_uid"]}/#{token["token_uid"]} parked"
+  nil
+end
+
+Dir.chdir(__dir__)
+
+graph_states = JSON.parse(File.read("graph_states.json"))
+jobs = JSON.parse(File.read("jobs.json"))
+
+next_graph_states = graph_states.fetch("graphs", []).map do |graph_state|
+  if graph_state["status"] == "finished"
+    graph_state
+  else
+    next_tokens = []
+    joins = graph_state["joins"] || {}
+    final_state = graph_state["result"]
+
+    graph_state.fetch("tokens", []).each do |token|
+      if GRAPH.join?(token["node"]) && token["from_node"]
+        process_join(graph_state, token, joins, next_tokens)
+        next
+      end
+
+      waiting_jobs = token.fetch("awaits", {}).values
+        .filter_map { |job_uid| job_for(jobs, job_uid) }
+        .select { |job| job["status"] == "pending" }
+      unless waiting_jobs.empty?
+        puts "#{graph_state["graph_uid"]}/#{token["token_uid"]} waiting #{waiting_jobs.map { |job| job["job_uid"] }.join(",")}"
+        next_tokens << token
+        next
+      end
+
+      step = GRAPH.step(
+        state: AsyncGraph.symbolize(token["state"]),
+        node: token["node"],
+        resolved: resolved_for(token, jobs)
+      )
+
+      case step
+      when AsyncGraph::Suspended
+        awaits = token.fetch("awaits", {}).dup
+        job_uids = step.requests.map do |request|
+          awaits[request.key] ||= queue_job(jobs, request)
+        end
+        puts "#{graph_state["graph_uid"]}/#{token["token_uid"]} suspended #{job_uids.join(",")}"
+        next_tokens << AsyncGraph.stringify(
+          token_uid: token["token_uid"],
+          node: step.node,
+          state: step.state,
+          fork_uid: token["fork_uid"],
+          branch: token["branch"],
+          from_node: token["from_node"],
+          awaits: awaits
+        )
+      when AsyncGraph::Advanced
+        puts "#{graph_state["graph_uid"]}/#{token["token_uid"]} advanced"
+        advanced_state = spawn_tokens(
+          graph_state["graph_uid"],
+          token,
+          step.state,
+          step.destinations,
+          next_tokens
+        )
+        final_state = advanced_state if advanced_state
+      when AsyncGraph::Finished
+        final_state = step.state
+      end
+    end
+
+    status = final_state && next_tokens.empty? && joins.empty? ? :finished : :running
+    puts "#{graph_state["graph_uid"]} finished" if status == :finished
+
+    {
+      graph_uid: graph_state["graph_uid"],
+      status: status,
+      tokens: next_tokens,
+      joins: joins,
+      result: final_state
+    }
+  end
+end
+
+File.write(
+  "graph_states.json",
+  JSON.pretty_generate(AsyncGraph.stringify(graphs: next_graph_states)) + "\n"
+)
+File.write("jobs.json", JSON.pretty_generate(jobs) + "\n")

data/examples/graph_states.json

@@ -0,0 +1,42 @@
+{
+  "graphs": [
+    {
+      "graph_uid": "graph-1",
+      "status": "finished",
+      "tokens": [],
+      "joins": {},
+      "result": {
+        "user_id": 7,
+        "left_ready": true,
+        "right_ready": true,
+        "left": {
+          "id": 7,
+          "name": "Ada-7"
+        },
+        "right": {
+          "score": 70
+        },
+        "message": "Ada-7 score=70"
+      }
+    },
+    {
+      "graph_uid": "graph-2",
+      "status": "finished",
+      "tokens": [],
+      "joins": {},
+      "result": {
+        "user_id": 8,
+        "left_ready": true,
+        "right_ready": true,
+        "left": {
+          "id": 8,
+          "name": "Ada-8"
+        },
+        "right": {
+          "score": 80
+        },
+        "message": "Ada-8 score=80"
+      }
+    }
+  ]
+}

data/examples/jobs.json

@@ -0,0 +1,50 @@
+{
+  "jobs": [
+    {
+      "job_uid": "job-1",
+      "kind": "fetch_profile",
+      "payload": {
+        "user_id": 7
+      },
+      "status": "done",
+      "result": {
+        "id": 7,
+        "name": "Ada-7"
+      }
+    },
+    {
+      "job_uid": "job-2",
+      "kind": "fetch_score",
+      "payload": {
+        "user_id": 7
+      },
+      "status": "done",
+      "result": {
+        "score": 70
+      }
+    },
+    {
+      "job_uid": "job-3",
+      "kind": "fetch_profile",
+      "payload": {
+        "user_id": 8
+      },
+      "status": "done",
+      "result": {
+        "id": 8,
+        "name": "Ada-8"
+      }
+    },
+    {
+      "job_uid": "job-4",
+      "kind": "fetch_score",
+      "payload": {
+        "user_id": 8
+      },
+      "status": "done",
+      "result": {
+        "score": 80
+      }
+    }
+  ]
+}

data/examples/reset.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "app_graph"
+
+Dir.chdir(__dir__)
+
+File.write(
+  "graph_states.json",
+  JSON.pretty_generate(
+    AsyncGraph.stringify(
+      graphs: [
+        {
+          graph_uid: "graph-1",
+          status: :running,
+          tokens: [{token_uid: "t1", node: GRAPH.entry, state: {user_id: 7}, fork_uid: nil, branch: nil, from_node: nil, awaits: {}}],
+          joins: {},
+          result: nil
+        },
+        {
+          graph_uid: "graph-2",
+          status: :running,
+          tokens: [{token_uid: "t1", node: GRAPH.entry, state: {user_id: 8}, fork_uid: nil, branch: nil, from_node: nil, awaits: {}}],
+          joins: {},
+          result: nil
+        }
+      ]
+    )
+  ) + "\n"
+)
+File.write("jobs.json", JSON.pretty_generate(jobs: []) + "\n")
+
+puts "reset"

data/examples/run.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+for file in app_graph.rb reset.rb graph_run.rb execute_jobs.rb; do
+  ruby -c "$file"
+done
+
+printf '\n== reset ==\n'
+ruby reset.rb
+cat graph_states.json
+cat jobs.json
+
+printf '\n== graph run 1 ==\n'
+ruby graph_run.rb
+cat graph_states.json
+cat jobs.json
+
+printf '\n== graph run 2 ==\n'
+ruby graph_run.rb
+cat graph_states.json
+cat jobs.json
+
+printf '\n== graph run 3 ==\n'
+ruby graph_run.rb
+cat graph_states.json
+cat jobs.json
+
+printf '\n== graph run 4 ==\n'
+ruby graph_run.rb
+cat graph_states.json
+cat jobs.json
+
+printf '\n== execute jobs ==\n'
+ruby execute_jobs.rb
+cat jobs.json
+
+printf '\n== graph run 5 ==\n'
+ruby graph_run.rb
+cat graph_states.json
+cat jobs.json

data/lib/async_graph/graph.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module AsyncGraph
+  FINISH = :__finish__
+
+  Request = Struct.new(:key, :kind, :payload, keyword_init: true)
+  Edge = Struct.new(:to, :branch, keyword_init: true)
+  AwaitSignal = Struct.new(:requests, keyword_init: true)
+
+  def self.symbolize(object)
+    case object
+    when Array then object.map { |value| symbolize(value) }
+    when Hash then object.each_with_object({}) { |(key, value), memo| memo[key.to_sym] = symbolize(value) }
+    else object
+    end
+  end
+
+  def self.stringify(object)
+    case object
+    when Array then object.map { |value| stringify(value) }
+    when Hash then object.each_with_object({}) { |(key, value), memo| memo[key.to_s] = stringify(value) }
+    else object
+    end
+  end
+
+  class Command < Struct.new(:update, :goto, keyword_init: true)
+    def self.goto(node) = new(goto: node)
+    def self.update(delta) = new(update: delta)
+    def self.update_and_goto(delta, node) = new(update: delta, goto: node)
+  end
+
+  class Advanced < Struct.new(:state, :destinations, keyword_init: true)
+    def suspended? = false
+    def finished? = false
+  end
+
+  class Suspended < Struct.new(:state, :node, :requests, keyword_init: true)
+    def suspended? = true
+    def finished? = false
+  end
+
+  class Finished < Struct.new(:state, keyword_init: true)
+    def suspended? = false
+    def finished? = true
+  end
+
+  # Interesting options for issuing multiple external jobs from one logical step:
+  # 1. Model fan-out explicitly in the graph as a diamond.
+  # 2. Use await.all(...) inside one node to queue a batch and suspend once.
+  # 3. Use a two-phase API such as await.defer + await.resolve_all.
+  class Await
+    def initialize(resolved)
+      @resolved = resolved
+    end
+
+    def call(key, kind, payload = {})
+      key = key.to_s
+      return @resolved[key] if @resolved.key?(key)
+
+      throw :await, AwaitSignal.new(requests: [Request.new(key:, kind:, payload:)])
+    end
+
+    def all(definitions)
+      normalized = definitions.to_h do |key, (kind, payload)|
+        [key.to_s, [kind, payload || {}]]
+      end
+
+      missing = normalized.filter_map do |key, (kind, payload)|
+        next if @resolved.key?(key)
+
+        Request.new(key:, kind:, payload:)
+      end
+
+      throw :await, AwaitSignal.new(requests: missing) unless missing.empty?
+
+      normalized.keys.to_h { |key| [key.to_sym, @resolved[key]] }
+    end
+
+    def to_proc = method(:call).to_proc
+  end
+
+  class Graph
+    attr_reader :entry
+
+    def initialize(&block)
+      @nodes = {}
+      @edges = Hash.new { |hash, key| hash[key] = [] }
+      @join_expects = {}
+      instance_eval(&block) if block
+    end
+
+    def node(name, &block) = @nodes[name.to_sym] = block
+
+    def edge(from, to, branch: nil)
+      if from.is_a?(Array)
+        @join_expects[to.to_sym] = from.map(&:to_sym)
+        from.each { |item| edge(item, to, branch: item) }
+      else
+        @edges[from.to_sym] << Edge.new(to: to.to_sym, branch: branch&.to_sym)
+      end
+    end
+
+    def set_entry_point(name) = @entry = name.to_sym
+    def set_finish_point(name) = edge(name, FINISH)
+
+    def step(state:, node:, resolved: {})
+      current = node.to_sym
+      return Finished.new(state:) if current == FINISH
+
+      await = Await.new(resolved)
+      result = catch(:await) { [:ok, call_node(@nodes.fetch(current), state, await)] }
+      return Suspended.new(state:, node: current, requests: result.requests) if result.is_a?(AwaitSignal)
+
+      Advanced.new(**advance(current, state, result.last))
+    end
+
+    def edges_from(node)
+      @edges[node.to_sym].yield_self { |edges| edges.empty? ? [Edge.new(to: FINISH)] : edges }
+    end
+
+    def join?(node) = @join_expects.key?(node.to_sym)
+    def join_for(node) = @join_expects.fetch(node.to_sym)
+
+    private
+
+    def call_node(node, state, await)
+      case node.arity
+      when 0 then node.call
+      when 1 then node.call(state, &await.to_proc)
+      else node.call(state, await)
+      end
+    end
+
+    def advance(node, state, result)
+      case result
+      when Hash
+        { state: state.merge(result), destinations: edges_from(node) }
+      when Command
+        {
+          state: state.merge(result.update || {}),
+          destinations: result.goto ? [Edge.new(to: result.goto.to_sym)] : edges_from(node)
+        }
+      else
+        { state: state, destinations: edges_from(node) }
+      end
+    end
+  end
+end

data/lib/async_graph/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AsyncGraph
+  VERSION = "0.1.0"
+end

data/lib/async_graph.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "async_graph/version"
+require_relative "async_graph/graph"

data/spec/async_graph_spec.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+RSpec.describe AsyncGraph::Graph do
+  it "suspends and resumes await.all in one node" do
+    graph = described_class.new do
+      node :merge do |state, await|
+        results = await.all(
+          profile: [:fetch_profile, {user_id: state[:user_id]}],
+          score: [:fetch_score, {user_id: state[:user_id]}]
+        )
+
+        {
+          profile: results[:profile],
+          score: results[:score]
+        }
+      end
+
+      set_entry_point :merge
+      set_finish_point :merge
+    end
+
+    step = graph.step(state: {user_id: 7}, node: graph.entry)
+
+    aggregate_failures do
+      expect(step).to be_a(AsyncGraph::Suspended)
+      expect(step.requests.map(&:key)).to eq(%w[profile score])
+      expect(step.requests.map(&:kind)).to eq(%i[fetch_profile fetch_score])
+    end
+
+    resumed = graph.step(
+      state: step.state,
+      node: step.node,
+      resolved: {
+        "profile" => {name: "Ada"},
+        "score" => {score: 70}
+      }
+    )
+
+    aggregate_failures do
+      expect(resumed).to be_a(AsyncGraph::Advanced)
+      expect(resumed.state).to eq(
+        user_id: 7,
+        profile: {name: "Ada"},
+        score: {score: 70}
+      )
+      expect(resumed.destinations.map(&:to)).to eq([AsyncGraph::FINISH])
+    end
+  end
+
+  it "builds a barrier edge from multiple sources" do
+    graph = described_class.new do
+      node :left do
+      end
+
+      node :right do
+      end
+
+      node :merge do
+      end
+
+      set_entry_point :left
+      edge %i[left right], :merge
+    end
+
+    aggregate_failures do
+      expect(graph.join?(:merge)).to eq(true)
+      expect(graph.join_for(:merge)).to eq(%i[left right])
+      expect(graph.edges_from(:left).map(&:to)).to eq([:merge])
+      expect(graph.edges_from(:right).map(&:to)).to eq([:merge])
+    end
+  end
+
+  it "applies command updates and explicit goto" do
+    graph = described_class.new do
+      node :start do
+        AsyncGraph::Command.update_and_goto({ok: true}, :done)
+      end
+
+      node :done do
+      end
+
+      set_entry_point :start
+      set_finish_point :done
+    end
+
+    step = graph.step(state: {}, node: graph.entry)
+
+    aggregate_failures do
+      expect(step).to be_a(AsyncGraph::Advanced)
+      expect(step.state).to eq(ok: true)
+      expect(step.destinations.map(&:to)).to eq([:done])
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "async_graph"

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: async-graph
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Author
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+- !ruby/object:Gem::Dependency
+  name: rspec_junit_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.1
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.14.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.14.2
+description: A minimal Ruby graph runtime that suspends on external work and resumes
+  later.
+email:
+- author@email.address
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".github/workflows/release.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- Gemfile
+- README.erb
+- README.md
+- Rakefile
+- async-graph.gemspec
+- bin/console
+- examples/app_graph.rb
+- examples/execute_jobs.rb
+- examples/graph_run.rb
+- examples/graph_states.json
+- examples/jobs.json
+- examples/reset.rb
+- examples/run.sh
+- lib/async_graph.rb
+- lib/async_graph/graph.rb
+- lib/async_graph/version.rb
+- spec/async_graph_spec.rb
+- spec/spec_helper.rb
+homepage: https://rubygems.org/gems/async-graph
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/example/async-graph
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.4
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Small async graph runtime with external job scheduling
+test_files: []