async-graph 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3e3bf481043bd72452272103c97734117490058de259428a68eef31fd264d02
-  data.tar.gz: fe632f6b44ae151a7a84de797f87dcbabfea0fa657f1f2fc89e44346ae2f0a04
+  metadata.gz: 9e191c8f8d75367ded4fb71dc739d1c337bc41b158e40577aaf06a054a0321f4
+  data.tar.gz: b82e743e0b5119862364200eb8ff558312cb7d0963dd7257e87b38f8895e5924
 SHA512:
-  metadata.gz: be4936d2a7d36d3935d179d74b7bf5715c1065f30e825b5e1a2e0ab04ee1f6cbbf528e736967c8c099df55d0b59bb72f39d4d906d964a84e67c9666215637edb
-  data.tar.gz: cde66865264df5b7d647c2d6704d8fed789c54e25ab7b3c27fe57c2d52e8ca63c01218bcf38d6db0b95d45a825e2641dd90a34db88d388e2426d5cd0861dfba4
+  metadata.gz: a351f8bdbb37c7b7da3d09ce4c63d965d9981d6ebeb97bd7473837909085d186c31e2d1efe2a28e46c9d3bd417b20f1cd851a7a4d44ef817360b026d249f7729
+  data.tar.gz: 1ad91c064b0dcd6bafd8bc8f62e987d6b909fb77f713eedadbe2581b6025e47a03d2ee1b36f2f04752718df9efb2fbbd743743ee837012053957634214ed2d7e

data/.github/workflows/ci.yml

@@ -4,15 +4,44 @@ on:
   push:
   pull_request:
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: "3.4.4"
           bundler-cache: true
       - run: bundle exec rake
-      - run: bundle exec rubocop
+      - name: Run RuboCop
+        run: |
+          mkdir -p results
+          set -o pipefail
+          git ls-files -z '*.rb' '*.gemspec' Gemfile Rakefile 'bin/*' \
+            | xargs -0 bundle exec rubocop --display-cop-names --extra-details --cache false --force-exclusion 2>&1 \
+            | tee results/rubocop.log
+      - name: Upload RuboCop log
+        if: failure()
+        uses: actions/upload-artifact@v6
+        with:
+          name: rubocop-log
+          path: results/rubocop.log
       - run: bash examples/run.sh
+  docs:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs-site
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: docs-site/package-lock.json
+      - run: npm ci
+      - run: npm run build

data/.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: withastro/action@v5
+        with:
+          path: docs-site
+          node-version: 24
+          package-manager: npm@11.6.2
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

data/.github/workflows/release.yml

@@ -4,18 +4,35 @@ on:
   push:
     branches: [main]
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   build_and_publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: "3.4.4"
-      - run: |
+      - run: bundle install
+      - id: gem_version
+        name: Check published gem version
+        run: |
+          current="$(ruby -e 'require_relative "lib/async-graph/version"; print AsyncGraph::VERSION')"
+          latest="$(ruby -rjson -ropen-uri -e 'begin; print JSON.parse(URI.open("https://rubygems.org/api/v1/versions/async-graph/latest.json", &:read))["version"]; rescue StandardError; end')"
+          echo "current=$current" >> "$GITHUB_OUTPUT"
+          echo "latest=$latest" >> "$GITHUB_OUTPUT"
+      - name: Publish gem
+        if: steps.gem_version.outputs.current != steps.gem_version.outputs.latest
+        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 }}
+      - name: Skip published version
+        if: steps.gem_version.outputs.current == steps.gem_version.outputs.latest
+        run: echo "async-graph ${CURRENT_VERSION} is already published; skipping release."
+        env:
+          CURRENT_VERSION: ${{ steps.gem_version.outputs.current }}

data/.gitignore

@@ -1,8 +1,23 @@
 /.bundle/
+.idea/
 /pkg/
 /results/*
 !/results/.gitkeep
 /.idea/workspace.xml
+/docs-site/.astro
+/docs-site/.vscode
 /examples/*.json
 /*.gem
 /*.iml
+/docs-site/dist/
+/docs-site/node_modules/
+/docs-site/npm-debug.log*
+/docs-site/yarn-debug.log*
+/docs-site/yarn-error.log*
+/docs-site/pnpm-debug.log*
+/docs-site/.env
+/docs-site/.env.production
+/docs-site/.DS_Store
+/docs-site/src/assets/houston.webp
+AGENTS.md
+**/.knowledge/

data/README.erb

@@ -1,12 +1,16 @@
 # AsyncGraph
+Published docs: <https://artyomb.github.io/async-graph/>
 
 AsyncGraph is a 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
+- runner helpers for opaque persisted run state and fan-out/join bookkeeping
 - barrier joins such as `edge %i[left right], :merge`
+- library-owned join processing for persisted branch tokens
 - `await.call(...)` for one external job
 - `await.all(...)` for multiple parallel jobs in one node
+- graph validation before execution
 
 ## Installation
 
@@ -42,10 +46,31 @@ resumed.state
 # => { user_id: 7, user: { id: 7, name: "Ada" } }
 ```
 
+For persisted multi-pass execution, `AsyncGraph::Runner` can create and advance a run
+snapshot while your application still owns persistence and external jobs.
+
 ## Demo
 
-The repository includes a runnable example in `examples/`:
+The repository includes two runnable examples in `examples/`:
+
+- persisted multi-pass flow with external job persistence:
 
 ```bash
 bash examples/run.sh
 ```
+
+- self-contained runner loop with inline `:add` / `:subtract` request handling:
+
+```bash
+ruby examples/all_in_one_runner.rb
+```
+
+## Documentation
+
+The repository also includes the Starlight source site in `docs-site/`.
+
+```bash
+cd docs-site
+npm install
+npm run dev
+```

data/README.md

@@ -1,12 +1,16 @@
 # AsyncGraph
+Published docs: <https://artyomb.github.io/async-graph/>
 
 AsyncGraph is a 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
+- runner helpers for opaque persisted run state and fan-out/join bookkeeping
 - barrier joins such as `edge %i[left right], :merge`
+- library-owned join processing for persisted branch tokens
 - `await.call(...)` for one external job
 - `await.all(...)` for multiple parallel jobs in one node
+- graph validation before execution
 
 ## Installation
 
@@ -42,10 +46,31 @@ resumed.state
 # => { user_id: 7, user: { id: 7, name: "Ada" } }
 ```
 
+For persisted multi-pass execution, `AsyncGraph::Runner` can create and advance a run
+snapshot while your application still owns persistence and external jobs.
+
 ## Demo
 
-The repository includes a runnable example in `examples/`:
+The repository includes two runnable examples in `examples/`:
+
+- persisted multi-pass flow with external job persistence:
 
 ```bash
 bash examples/run.sh
 ```
+
+- self-contained runner loop with inline `:add` / `:subtract` request handling:
+
+```bash
+ruby examples/all_in_one_runner.rb
+```
+
+## Documentation
+
+The repository also includes the Starlight source site in `docs-site/`.
+
+```bash
+cd docs-site
+npm install
+npm run dev
+```

data/examples/all_in_one_runner.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../lib/async-graph"
+
+runner = AsyncGraph::Runner.new(
+  AsyncGraph::Graph.new do
+    node :calculate do |state, await|
+      results = await.all(
+        added: [:add, {left: state[:left], right: state[:right]}],
+        subtracted: [:subtract, {left: state[:total], right: state[:discount]}]
+      )
+
+      {
+        added: results[:added],
+        subtracted: results[:subtracted],
+        answer: results[:added] - results[:subtracted]
+      }
+    end
+
+    set_entry_point :calculate
+    set_finish_point :calculate
+  end
+)
+
+results = {}
+run = runner.start_run state: {left: 7, right: 5, total: 20, discount: 3}
+
+until run.finished?
+  run = runner.advance_run(
+    run: run,
+    resolved_for: lambda do |token|
+      token[:awaits].each_with_object({}) do |(key, request_id), memo|
+        memo[key.to_s] = results[request_id] if results.key?(request_id)
+      end
+    end
+  ) do |request|
+    results[request.key] =
+      case request.kind
+      when :add then request.payload[:left] + request.payload[:right]
+      when :subtract then request.payload[:left] - request.payload[:right]
+      end
+
+    request.key
+  end
+end
+
+puts JSON.pretty_generate(run.result)

data/examples/app_graph.rb

@@ -33,3 +33,5 @@ GRAPH = AsyncGraph::Graph.new do
   edge %i[left right], :merge
   set_finish_point :merge
 end
+
+RUNNER = AsyncGraph::Runner.new(GRAPH)

data/examples/execute_jobs.rb

@@ -4,25 +4,25 @@ require "json"
 
 Dir.chdir(__dir__)
 
-jobs = JSON.parse(File.read("jobs.json"))
+jobs = JSON.parse(File.read("jobs.json"), symbolize_names: true)
 
-jobs.fetch("jobs", []).each do |job|
-  next unless job["status"] == "pending"
+jobs.fetch(:jobs, []).each do |job|
+  next unless job[:status] == "pending"
 
-  job["result"] =
-    case job["kind"]
+  job[:result] =
+    case job[:kind]
     when "fetch_profile"
-      user_id = job.dig("payload", "user_id")
-      {"id" => user_id, "name" => "Ada-#{user_id}"}
+      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}
+      user_id = job.dig(:payload, :user_id)
+      {score: user_id * 10}
     end
 
-  next unless job["result"]
+  next unless job[:result]
 
-  job["status"] = "done"
-  puts "done #{job["job_uid"]} #{job["kind"]}"
+  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

@@ -3,178 +3,42 @@
 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))
+def advance_graph_state!(graph_state, job_list, jobs_by_uid)
+  graph_uid = graph_state.fetch(:graph_uid)
+  next_run = RUNNER.advance_run(
+    run: graph_state.fetch(:run),
+    resolved_for: lambda do |token|
+      token.fetch(:awaits, {}).each_with_object({}) do |(key, job_uid), memo|
+        job = jobs_by_uid[job_uid]
+        memo[key.to_s] = job[:result] if job&.[](:status) == "done"
+      end
     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
+  ) do |request|
+    job_uid = "job-#{job_list.size + 1}"
+    job = jobs_by_uid[job_uid] = {
+      job_uid: job_uid,
+      kind: request.kind.to_s,
+      payload: request.payload,
+      status: "pending"
+    }
+    job_list << job
+    job_uid
   end
 
-  joins[bucket_key] = bucket
-  puts "#{graph_state["graph_uid"]}/#{token["token_uid"]} parked"
-  nil
+  puts "#{graph_uid} finished" if next_run.finished?
+  graph_state[:run] = next_run.to_h
 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
+graph_states = JSON.parse(File.read("graph_states.json"), symbolize_names: true)
+jobs = JSON.parse(File.read("jobs.json"), symbolize_names: true)
+job_list = jobs.fetch(:jobs)
+jobs_by_uid = job_list.to_h { |job| [job[:job_uid], job] }
 
-      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
+graph_states.fetch(:graphs, [])
+  .reject { it.dig(:run, :status) == "finished" }
+  .each { advance_graph_state!(it, job_list, jobs_by_uid) }
 
-File.write(
-  "graph_states.json",
-  JSON.pretty_generate(AsyncGraph.stringify(graphs: next_graph_states)) + "\n"
-)
+File.write("graph_states.json", JSON.pretty_generate(graph_states) + "\n")
 File.write("jobs.json", JSON.pretty_generate(jobs) + "\n")

data/examples/reset.rb

@@ -8,24 +8,16 @@ 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
-        }
-      ]
-    )
+    graphs: [
+      {
+        graph_uid: "graph-1",
+        run: RUNNER.start_run(state: {user_id: 7}).to_h
+      },
+      {
+        graph_uid: "graph-2",
+        run: RUNNER.start_run(state: {user_id: 8}).to_h
+      }
+    ]
   ) + "\n"
 )
 File.write("jobs.json", JSON.pretty_generate(jobs: []) + "\n")

data/examples/run.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 
 cd "$(dirname "$0")"
 
-for file in app_graph.rb reset.rb graph_run.rb execute_jobs.rb; do
+for file in app_graph.rb reset.rb graph_run.rb execute_jobs.rb all_in_one_runner.rb; do
   ruby -c "$file"
 done
 
@@ -40,3 +40,6 @@ printf '\n== graph run 5 ==\n'
 ruby graph_run.rb
 cat graph_states.json
 cat jobs.json
+
+printf '\n== all-in-one runner ==\n'
+ruby all_in_one_runner.rb