robot_lab-ractor 0.1.0 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24693d3b0371d41a878e7112c904e01bbf65d46f4cded26fe78b45856c49716c
-  data.tar.gz: e7fdf7b457efb4e5359f9ccf36afd50823f2fe15d11e5c56d6dd2fe93ba9f959
+  metadata.gz: 7df9c3ab4660c44f064946a5a90f071df1ad03baa1b4cac8c3259156a35be70b
+  data.tar.gz: 0fb20202b60255f45be1b423d5fa5870730cfd4fbf3dbaee1ec601eb72a87f59
 SHA512:
-  metadata.gz: 5ed65c66df3ef0d840ab8f4745cf2a3b2fe82c6216f0458480336ec3274fafde8ce8b2c610526de66f00cdf9473ab52961b6f818166b64752a911a377cb21a34
-  data.tar.gz: 9024af8c7f52c239b8549e04eab3c9f852622264a3f3656aac4d41cfc72ccb41707b07ec7749622aaddb4c8ff95d21af0c7e0aa106bedf25c4a58d7de15e9095
+  metadata.gz: '0418c60678b46d1c7b9e3a625f8e2c3b1ebf789a2f526daea6f05d5c8a9046a11e54217bea1dd8fd15a50bae6115ea634907e002adc96d7d06f736c626f05d20'
+  data.tar.gz: c8800eee270d7987d17658a97c7dce82074ce8db09b67d7a598d92c1e29b15138d07e242f4a5de86fe0a812cadbb10c0ce02736da6d80f60cea36f24b22b4779

data/.envrc

@@ -1 +1,3 @@
+source_up
 export RR=`pwd`
+export BUNDLE_GEMFILE=Gemfile

data/.loki

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# robot_lab-ractor — CPU parallelism via Ractors.
+
+import_up "repo_dev.loki"
+
+class Tasks
+  @@gem_name ||= "robot_lab-ractor".freeze
+
+  header "robot_lab-ractor v#{gem_version} — CPU-parallel robot execution"
+end

data/.quality/reek_baseline.txt

@@ -0,0 +1,3 @@
+1	lib/robot_lab/ractor_boundary.rb
+3	lib/robot_lab/ractor_network_scheduler.rb
+1	lib/robot_lab/ractor_worker_pool.rb

data/.rubocop.yml

@@ -0,0 +1 @@
+inherit_from: ../.rubocop-base.yml

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 ## [Unreleased]
 
+### Added
+- `.loki` Asgard task file: `test`, `rubocop`, `rubocop_fix`, `flog`, `flay`, `quality`, `build`, `install`, `release`, and `console` tasks via the Asgard task runner
+- `flay_check` Rake task: structural code duplication gate (mass threshold 50); integrated into the `quality` Rake task
+- `flay` and `minitest-reporters` gems added to development dependencies
+- `test_output.txt`, `flay_output.txt`, `flog_output.txt`, and `rubocop_output.txt` added to `.gitignore`
+
+### Changed
+- `test/test_helper.rb`: test output redirected to `test_output.txt` via `$stdout` reassignment; `TerminalSummaryReporter` prints a single PASS/FAIL summary line to the terminal
+- `Rakefile`: `rubocop` and `rubocop_fix` tasks removed (now owned by Asgard); `flay_check` integrated into the `quality` gate
+
+## [0.2.1] - 2026-05-19
+
+### Added
+- `RactorWorkerPool` — shared pool of Ractor workers; tools marked `ractor_safe true` are automatically routed through it instead of running inline
+- `RactorNetworkScheduler` — DAG-aware parallel execution of robot networks using Ractors; activated via `parallel_mode: :ractor` on a network
+- `RactorBoundary` — `freeze_deep` utility for making values Ractor-shareable; raises `RactorBoundaryError` for values that cannot cross Ractor boundaries
+- `RactorMemoryProxy` — thread-safe proxy exposing `RobotLab::Memory` to Ractor workers via `Ractor::Wrapper`
+- `RactorJob` — Ractor-shareable frozen job value object used internally by the pool and scheduler
+- `ractor_safe` class-level DSL for `RubyLLM::Tool` / `RobotLab::Tool` subclasses; inherited by subclasses
+- `RobotLab.ractor_pool` / `.shutdown_ractor_pool` — process-level pool lifecycle methods added to the `RobotLab` module
+- Ractor Parallelism guide (`docs/guides/ractor-parallelism.md`) covering both CPU-bound tools and parallel network pipelines
+
+### Changed
+- Version synchronized with robot_lab core 0.2.1
+
 ## [0.1.0] - 2026-05-07
 
 - Initial release

data/CLAUDE.md

@@ -0,0 +1,71 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Gem Does
+
+`robot_lab-ractor` enables CPU-parallel execution in RobotLab via Ruby Ractors. It provides a worker pool for CPU-bound tools and a dependency-aware network scheduler for running robot pipelines across Ractor workers.
+
+## Commands
+
+```bash
+bundle exec rake test        # Run full test suite
+ruby -Ilib:test test/<file>  # Run a single test file
+```
+
+## CRITICAL: Never define `module RobotLab::Ractor`
+
+`lib/robot_lab/ractor.rb` intentionally does **not** open `module RobotLab::Ractor`. Defining that module would shadow Ruby's built-in `Ractor` class for all code inside the `RobotLab` namespace, breaking `Ractor.new`, `Ractor.make_shareable`, etc. throughout the codebase. The version constant lives in `RobotLab::RactorPool::VERSION` to avoid this clash.
+
+## Architecture
+
+**`RactorWorkerPool`** (`ractor_worker_pool.rb`) — Pool of Ractor workers for CPU-bound, Ractor-safe tools. Submit a job from any thread; the result is returned synchronously via a per-job `RactorQueue`.
+
+```ruby
+pool = RactorWorkerPool.new(size: 4)      # :auto = Etc.nprocessors
+result = pool.submit("MyTool", { arg: "value" })
+pool.shutdown
+```
+
+Accessed globally via `RobotLab.ractor_pool` / `RobotLab.shutdown_ractor_pool`.
+
+**`RactorNetworkScheduler`** (`ractor_network_scheduler.rb`) — Schedules frozen `RobotSpec` payloads across Ractor workers in dependency order. Entry-point robots (`:none` deps) dispatch immediately; dependent robots dispatch once all named deps complete.
+
+```ruby
+scheduler = RactorNetworkScheduler.new(memory: shared_memory)
+results = scheduler.run_pipeline([
+  { spec: analyst_spec, depends_on: :none },
+  { spec: writer_spec,  depends_on: ["analyst"] }
+], message: "Analyse this")
+scheduler.shutdown
+```
+
+**`RactorBoundary`** (`ractor_boundary.rb`) — Utility for crossing Ractor boundaries. `freeze_deep(obj)` recursively freezes Hash/Array structures and calls `Ractor.make_shareable`. Raises `RactorBoundaryError` if the value cannot be made shareable (e.g. a live IO or Proc).
+
+**`RactorMemoryProxy`** (`ractor_memory_proxy.rb`) — Wraps a `Memory` instance via `Ractor::Wrapper` so Ractor workers can read and write shared state. Only `get`, `set`, and `keys` are proxied; closures and subscriptions are not Ractor-safe and must use the thread-side Memory directly.
+
+**Data Carriers** (`ractor_job.rb`) — Three frozen `Data.define` structs:
+- `RactorJob` — work item: `id`, `type`, `payload`, `reply_queue`
+- `RactorJobError` — serialised error: `message`, `backtrace`
+- `RobotSpec` — frozen robot descriptor: `name`, `template`, `system_prompt`, `config_hash`, `hook_classes`
+
+## Tool Requirements for Ractor Safety
+
+Tools submitted to `RactorWorkerPool` must:
+1. Be instantiated fresh per call (no shared mutable state)
+2. Accept only Ractor-shareable arguments (frozen strings, numbers, frozen hashes)
+3. Return a value that can be `Ractor.make_shareable` (frozen or deep-freezable)
+
+LLM calls via `ruby_llm` are NOT Ractor-safe — do not submit tools that call the LLM to the pool.
+
+## Key Constraints
+
+- Shutdown is via poison-pill (one `nil` per worker) — always call `shutdown` to avoid orphaned Ractors.
+- `RactorNetworkScheduler.process_job` and `RactorWorkerPool.process_job` must be class methods — Ractors cannot call instance methods on objects defined outside their scope.
+- `RobotSpec#hook_classes` must be an array of frozen class references, not instances.
+
+## Testing
+
+- Minitest with SimpleCov (branch coverage tracked, no minimum threshold enforced yet)
+- Tests use RobotLab stubs (the full `robot_lab` gem is NOT loaded in tests — see `test_helper.rb`)
+- Coverage baseline: ~55% line / ~32% branch

data/Rakefile

@@ -1,8 +1,132 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "minitest/test_task"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
-Minitest::TestTask.create
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb', 'test/**/test_*.rb'].exclude('**/*_helper.rb')
+  t.verbose = true
+  t.ruby_opts << '-rtest_helper'
+end
 
 task default: :test
+
+desc 'Run tests with verbose output'
+task :test_verbose do
+  ENV['TESTOPTS'] = '--verbose'
+  Rake::Task[:test].invoke
+end
+
+desc 'Run a single test file'
+task :test_file, [:file] do |_t, args|
+  ruby "test/#{args[:file]}"
+end
+
+desc 'Check code complexity with Flog (warn >=20, fail >=50)'
+task :flog_check do
+  require 'flog'
+
+  method_warn = 20.0
+  method_fail = 50.0
+
+  flogger = Flog.new(all: true)
+  flogger.flog(*Dir.glob('lib/**/*.rb'))
+
+  warnings = []
+  failures = []
+
+  flogger.each_by_score do |method, score|
+    next if method.end_with?('#none')
+
+    if score > method_fail
+      failures << "#{format('%.1f', score)}: #{method}"
+    elsif score > method_warn
+      warnings << "#{format('%.1f', score)}: #{method}"
+    end
+  end
+
+  unless warnings.empty?
+    puts "\nFlog warnings (#{method_warn}–#{method_fail}) — target for future refactoring:"
+    warnings.each { |v| puts "  #{v}" }
+  end
+
+  if failures.empty?
+    puts "\nFlog: no methods exceed the failure threshold (>=#{method_fail})"
+  else
+    puts "\nFlog failures (>=#{method_fail}) — must be refactored:"
+    failures.each { |v| puts "  #{v}" }
+    abort "\nFlog quality gate failed: #{failures.size} method(s) exceed #{method_fail}"
+  end
+end
+
+desc 'Check for structural code duplication with Flay (mass >= 50)'
+task :flay_check do
+  require 'flay'
+
+  mass_threshold = 50
+
+  flay = Flay.new({ mass: mass_threshold, diff: false, verbose: false, summary: false, timeout: 60 })
+  flay.process(*Dir.glob('lib/**/*.rb'))
+  flay.analyze
+
+  if flay.hashes.empty?
+    puts "\nFlay: no structural duplication detected (mass >= #{mass_threshold})"
+  else
+    puts "\nFlay found structural duplication (mass >= #{mass_threshold}):"
+    flay.report
+    abort "\nFlay quality gate failed: #{flay.hashes.length} pattern(s) detected"
+  end
+end
+
+desc 'Run all quality checks: tests (with coverage), RuboCop, Flog, and Flay'
+task :quality do
+  gates = [
+    ['Tests + Coverage', 'bundle exec rake test'],
+    ['RuboCop',          'bundle exec rubocop'],
+    ['Flog Complexity',  'bundle exec rake flog_check'],
+    ['Flay Duplication', 'bundle exec rake flay_check']
+  ]
+
+  results = gates.map do |label, command|
+    puts "\n#{'=' * 60}"
+    puts "Quality Gate: #{label}"
+    puts '=' * 60
+    [label, system(command) ? :pass : :fail]
+  end
+
+  green = ->(s) { "\e[32m#{s}\e[0m" }
+  red   = ->(s) { "\e[31m#{s}\e[0m" }
+  width = results.map { |label, _| label.length }.max
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Gate Summary'
+  puts '=' * 60
+  results.each do |label, status|
+    badge = status == :pass ? green.call('PASS') : red.call('FAIL')
+    puts "  [#{badge}] #{label.ljust(width)}"
+  end
+  puts '-' * 60
+
+  passed = results.count { |_, s| s == :pass }
+  failed = results.count { |_, s| s == :fail }
+  tally  = "#{passed} passed, #{failed} failed"
+  puts "  #{failed.zero? ? green.call(tally) : red.call(tally)}"
+  puts '=' * 60
+
+  abort "\n#{red.call('Quality gate failed.')}" unless failed.zero?
+  puts "\n#{green.call('All quality gates passed.')}"
+end
+
+namespace :docs do
+  desc 'Build MkDocs documentation'
+  task :build do
+    sh 'mkdocs build'
+  end
+
+  desc 'Serve MkDocs documentation locally on http://localhost:8000'
+  task :serve do
+    sh 'mkdocs serve'
+  end
+end

data/docs/guides/ractor-parallelism.md

@@ -229,6 +229,71 @@ Values written via `set` are automatically deep-frozen before crossing the bound
 
 ---
 
+## Hooks in Ractor Workers
+
+`RactorNetworkScheduler` carries a robot's registered `RobotLab::Hook` handler
+classes across the Ractor boundary so the full hook pipeline still fires
+inside each worker.
+
+When the scheduler builds a `RobotSpec`, it collects handler classes from all
+three registration levels and stores them in the frozen `hook_classes` field:
+
+```ruby
+def ractor_hook_classes_for(robot)
+  [RobotLab.hooks, @hooks, robot.hooks]
+    .flat_map { |r| r.registrations.map(&:handler_class) }
+    .uniq.freeze
+end
+```
+
+| Registration level | Collected by |
+|---|---|
+| `RobotLab.on(Hook)` | `RobotLab.hooks` (global) |
+| `network.on(Hook)` | `@hooks` (network) |
+| `robot.on(Hook)` | `robot.hooks` (robot) |
+
+Inside each worker, the scheduler re-registers the handlers on the freshly
+built robot before running it:
+
+```ruby
+spec.hook_classes.each { |handler| robot.on(handler) }
+robot.run(message)   # full hook pipeline fires here
+```
+
+This works because a Hook handler is a Ruby **class**, and classes are
+Ractor-shareable constants — they cross the boundary without any
+serialization.
+
+### Writing a Ractor-Safe Hook
+
+A hook handler that may run inside a Ractor worker must follow the same
+statelessness rules as a Ractor-safe tool:
+
+- **No class-level state.** `@ivars` set on the class object live in the main
+  Ractor; non-main Ractors cannot read or write them, even when the values
+  themselves would be shareable.
+- **Accumulate events on the context, not the class.** Push results into
+  `ctx.local` (a plain object local to that Ractor's run) and return them as
+  part of the worker's result tuple so the main thread can aggregate them
+  after `Ractor#value`.
+- **Avoid `$stdout.puts` for anything you need interleaved with main-thread
+  output.** Output from non-main Ractors is buffered per-Ractor and only
+  flushes at Ractor exit. `Kernel#warn` is silently dropped. Reading the
+  `STDOUT` constant raises `IsolationError`. `$stderr.puts` and a
+  `File.open(frozen_path, "a")` opened fresh inside the worker are both safe.
+- **`on_error` fires inside the failing Ractor**, before the error propagates
+  back to the main thread. Surface whatever you need via the return tuple —
+  the main thread only learns of the failure when it calls `worker.value`.
+
+`examples/03_ractor_hooks.rb` walks through all of this with two example
+handlers (`TraceHook`, `PerfHook`) plus `RobotLab::Xyzzy` — a fully
+Ractor-safe tracer covering all five hook families (`run`, `llm_generation`,
+`tool_call`, `network_run`, `task`) — run directly against the hook mechanic
+without touching `ruby_llm` (which has class-level Proc callbacks that
+prevent construction inside Ractors today).
+
+---
+
 ## The Frozen-Data Contract
 
 Everything that crosses a Ractor boundary must be Ractor-shareable: frozen strings, frozen hashes, frozen arrays, `Data.define` structs, and integers/symbols/nil.
@@ -356,6 +421,16 @@ at_exit { RobotLab.shutdown_ractor_pool }
 
 ---
 
+## Runnable Examples
+
+- `examples/01_ractor_tools.rb` — CPU-bound tools routed through `RactorWorkerPool`
+- `examples/02_ractor_network.rb` — a robot network run via `RactorNetworkScheduler`
+- `examples/03_ractor_hooks.rb` — the hook system firing inside Ractor workers (no LLM API key required)
+
+```bash
+bundle exec ruby examples/03_ractor_hooks.rb
+```
+
 ## Next Steps
 
 - [Using Tools](using-tools.md) — Tool definitions and configuration

data/docs/index.md

@@ -60,6 +60,12 @@ pool = RobotLab.ractor_pool
 RobotLab.shutdown_ractor_pool
 ```
 
+## Examples
+
+- `examples/01_ractor_tools.rb` — CPU-bound tools through `RactorWorkerPool`
+- `examples/02_ractor_network.rb` — a robot network run via `RactorNetworkScheduler`
+- `examples/03_ractor_hooks.rb` — the hook system firing inside Ractor workers (no LLM API key required)
+
 ## Links
 
 - [Ractor Parallelism Guide](guides/ractor-parallelism.md)

data/examples/{29_ractor_tools.rb → 01_ractor_tools.rb}

@@ -26,8 +26,7 @@
 #   SHA-256 rounds (~320 ms on modern hardware) so the 4-6× speedup is
 #   clearly visible on a 6-core machine.
 
-require "robot_lab"
-require "robot_lab/ractor"
+require_relative "common"
 require "digest"
 
 # Always shut down the pool when the process exits.
@@ -114,12 +113,7 @@ end
 # Demo
 # =============================================================================
 
-puts "=" * 62
-puts "Example 29: Ractor-Safe CPU Tools"
-puts "=" * 62
-puts
-
-DIVIDER = ("─" * 54).freeze
+banner("Ractor-Safe CPU Tools")
 
 SAMPLE_TEXTS = [
   "Ruby makes programmer happiness a first-class concern in language design.",
@@ -130,10 +124,7 @@ SAMPLE_TEXTS = [
   "Simplicity is the ultimate sophistication in software architecture."
 ].freeze
 
-# ── 1. ractor_safe? flags ─────────────────────────────────────
-
-puts "1.  ractor_safe? flags"
-puts "    #{DIVIDER}"
+section("1.  ractor_safe? flags")
 
 {
   "WordStatsTool"     => WordStatsTool,
@@ -146,10 +137,7 @@ puts "    #{DIVIDER}"
 end
 puts
 
-# ── 2. RactorBoundary.freeze_deep ─────────────────────────────
-
-puts "2.  RactorBoundary.freeze_deep"
-puts "    #{DIVIDER}"
+section("2.  RactorBoundary.freeze_deep")
 
 nested = { tags: ["ruby", "ractor"], meta: { version: 2 } }
 frozen = RobotLab::RactorBoundary.freeze_deep(nested)
@@ -170,11 +158,8 @@ rescue RobotLab::RactorBoundaryError => e
 end
 puts
 
-# ── 3. Single pool submissions ─────────────────────────────────
-
 pool = RobotLab.ractor_pool
-puts "3.  Worker pool  (#{pool.size} Ractors — one per CPU core)"
-puts "    #{DIVIDER}"
+section("3.  Worker pool  (#{pool.size} Ractors — one per CPU core)")
 
 sample = SAMPLE_TEXTS.first
 
@@ -185,10 +170,7 @@ r = pool.submit("ReadabilityTool", { text: sample })
 puts "    ReadabilityTool: words_per_sentence=#{r[:words_per_sentence]}  long_word_pct=#{r[:long_word_pct]}%"
 puts
 
-# ── 4. ToolError propagation ───────────────────────────────────
-
-puts "4.  ToolError propagation"
-puts "    #{DIVIDER}"
+section("4.  ToolError propagation")
 puts "    Submitting nil as :text (WordStatsTool will call nil.scan — NoMethodError)"
 puts
 
@@ -200,10 +182,7 @@ rescue RobotLab::ToolError => e
 end
 puts
 
-# ── 5. Parallel batch vs sequential ───────────────────────────
-
-puts "5.  Parallel batch — #{SAMPLE_TEXTS.length} jobs, each doing #{HeavyDigestTool::ROUNDS.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1_').reverse} SHA-256 rounds"
-puts "    #{DIVIDER}"
+section("5.  Parallel batch — #{SAMPLE_TEXTS.length} jobs, #{HeavyDigestTool::ROUNDS.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1_').reverse} SHA-256 rounds each")
 
 # Parallel: one Thread per job, all submitted simultaneously.
 t0       = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -230,13 +209,8 @@ puts
 puts "    First result (truncated digest): #{parallel_results.first}"
 puts
 
-# ── 6. Shutdown ────────────────────────────────────────────────
-
-puts "6.  Shutdown"
-puts "    #{DIVIDER}"
+section("6.  Shutdown")
 RobotLab.shutdown_ractor_pool
 puts "    Pool shut down cleanly (poison-pill × #{pool.size} workers)."
 puts
-puts "=" * 62
-puts "Example 29 complete."
-puts "=" * 62
+hr

data/examples/{30_ractor_network.rb → 02_ractor_network.rb}

@@ -30,15 +30,9 @@
 #   bundle exec ruby examples/30_ractor_network.rb              # Parts 1 & 2
 #   ANTHROPIC_API_KEY=key ruby examples/30_ractor_network.rb    # Parts 1, 2 & 3
 
-require "robot_lab"
-require "robot_lab/ractor"
+require_relative "common"
 
-puts "=" * 62
-puts "Example 30: Ractor Network Scheduler"
-puts "=" * 62
-puts
-
-DIVIDER = ("─" * 54).freeze
+banner("Ractor Network Scheduler")
 
 # =============================================================================
 # Part 1: Simulated scheduler — dependency waves and timing
@@ -72,8 +66,7 @@ LATENCIES = {
 #
 #   Speedup    ≈ 1.7×
 
-puts "── Part 1: Simulated parallel run (no API key) ───────────"
-puts
+section("Part 1: Simulated parallel run (no API key)")
 
 # SimulatedScheduler overrides execute_spec so that instead of
 # constructing a real Robot and calling the LLM, it just sleeps for
@@ -139,8 +132,7 @@ puts
 # Part 2: Network.new(parallel_mode: :ractor) API
 # =============================================================================
 
-puts "── Part 2: Network.new(parallel_mode: :ractor) ───────────"
-puts
+section("Part 2: Network.new(parallel_mode: :ractor)")
 
 # When parallel_mode: :ractor is set on a Network, network.run(message:)
 # routes through RactorNetworkScheduler instead of SimpleFlow::Pipeline.
@@ -196,19 +188,16 @@ puts
 # =============================================================================
 
 unless ENV["ANTHROPIC_API_KEY"]
-  puts "── Part 3: Live LLM run ──────────────────────────────────"
+  section("Part 3: Live LLM run")
   puts "   Set ANTHROPIC_API_KEY to run the real pipeline."
   puts "   Expected behavior: headline_finder, background_brief, and"
   puts "   fact_checker run in parallel; report_writer follows."
   puts
-  puts "=" * 62
-  puts "Example 30 complete."
-  puts "=" * 62
+  hr
   exit 0
 end
 
-puts "── Part 3: Live LLM run (ANTHROPIC_API_KEY detected) ─────"
-puts
+section("Part 3: Live LLM run (ANTHROPIC_API_KEY detected)")
 
 puts "  Running 4-robot research pipeline on:"
 puts "  \"#{topic}\""
@@ -250,6 +239,4 @@ rescue RobotLab::Error => e
 end
 
 puts
-puts "=" * 62
-puts "Example 30 complete."
-puts "=" * 62
+hr