If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ruby-concurrency/concurrent-ruby shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3d ago
• 28+ active contributors
• Distributed ownership (top contributor 42% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ruby-concurrency/concurrent-ruby repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ruby-concurrency/concurrent-ruby.

What it runs against: a local clone of ruby-concurrency/concurrent-ruby — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ruby-concurrency/concurrent-ruby | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ruby-concurrency/concurrent-ruby. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ruby-concurrency/concurrent-ruby.git
#   cd concurrent-ruby
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ruby-concurrency/concurrent-ruby and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ruby-concurrency/concurrent-ruby(\\.git)?\\b" \\
  && ok "origin remote is ruby-concurrency/concurrent-ruby" \\
  || miss "origin remote is not ruby-concurrency/concurrent-ruby (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/concurrent-ruby.rb" \\
  && ok "lib/concurrent-ruby.rb" \\
  || miss "missing critical file: lib/concurrent-ruby.rb"
test -f "lib/concurrent/agent.rb" \\
  && ok "lib/concurrent/agent.rb" \\
  || miss "missing critical file: lib/concurrent/agent.rb"
test -f "lib/concurrent/future.rb" \\
  && ok "lib/concurrent/future.rb" \\
  || miss "missing critical file: lib/concurrent/future.rb"
test -f "lib/concurrent/executor/executor_service.rb" \\
  && ok "lib/concurrent/executor/executor_service.rb" \\
  || miss "missing critical file: lib/concurrent/executor/executor_service.rb"
test -f "lib/concurrent/synchronization.rb" \\
  && ok "lib/concurrent/synchronization.rb" \\
  || miss "missing critical file: lib/concurrent/synchronization.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ruby-concurrency/concurrent-ruby"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Concurrent Ruby is a production-grade concurrency toolkit providing thread-safe abstractions inspired by Erlang, Clojure, and Scala. It includes agents, futures, promises, thread pools, channels, actors, supervisors, and dataflow primitives—all designed to work consistently across MRI, JRuby, and TruffleRuby without external dependencies. Monolithic gem structure: lib/ contains core Ruby abstractions (agents, futures, promises, executors, thread pools); ext/ has optional JRuby and C extensions for performance; docs-source/ contains comprehensive markdown + runnable examples; spec/ (inferred from .rspec) contains test suite. Three separate gemspecs allow users to depend on core (concurrent-ruby), native extensions (concurrent-ruby-ext), or experimental features (concurrent-ruby-edge) independently.

Ruby backend developers and systems engineers building concurrent, multi-threaded applications who need safe abstractions for async work, actor-based messaging, thread pooling, and coordination primitives without learning disparate libraries or managing raw Thread APIs.

Highly mature and actively developed. The repo shows 1.46M lines of Ruby code with comprehensive CI (GitHub Actions in .github/workflows/ci.yml), test suites implied by .rspec config, and extensive documentation under docs-source/. Multiple gemspecs (concurrent-ruby.gemspec, concurrent-ruby-ext.gemspec, concurrent-ruby-edge.gemspec) indicate stable versioning. CHANGELOG.md and semantic versioning through gem releases confirm long-term maintenance and backward compatibility guarantees.

Low risk for core library; zero external dependencies is a strength. The 'edge' gem variant (concurrent-ruby-edge.gemspec) signals experimental features separate from stable releases, mitigating breaking-change exposure. Primary risk: single-maintainer or small team dependency—monitor CONTRIBUTORS to verify active stewardship. Java and C extensions in the codebase (405K Java, 12K C) add complexity for cross-platform compatibility but are optional (ext) not mandatory.

Active development tracked via Rakefile, .github/workflows/, and release.yml automation. The dependabot.yml indicates dependency scanning. docs-source/ examples (celluloid_benchmark.rb, supervision_tree examples, channel/dataflow demos) suggest recent focus on actor systems, supervision trees, and documentation completeness. Experimental features segregated in -edge gem suggest ongoing research into new concurrency patterns.

Clone and install: git clone https://github.com/ruby-concurrency/concurrent-ruby.git && cd concurrent-ruby && bundle install. Run tests: rake spec. Run examples: ruby docs-source/actor/quick.in.rb or similar. Build gems: gem build concurrent-ruby.gemspec.

Daily commands: Development: bundle exec rake runs default tasks (tests + docs). Run specific test: bundle exec rspec spec/concurrent/path_spec.rb. Generate docs: yard (via .yardopts config). Run a demo: cd docs-source/actor && ruby quick.in.rb. Build all gems: rake gem:build.

• lib/concurrent-ruby.rb — Main entry point that loads all core concurrency abstractions; every contributor must understand the gem's public API surface.
• lib/concurrent/agent.rb — Core agent implementation providing shared mutable state with serialized updates; foundational to the Erlang-inspired execution model.
• lib/concurrent/future.rb — Promise/future abstraction for asynchronous computation; one of the most heavily used primitives in the library.
• lib/concurrent/executor/executor_service.rb — Abstract base for all thread pool and executor implementations; all async work routes through executors.
• lib/concurrent/synchronization.rb — Synchronization primitives and locking abstractions used across all concurrent utilities to ensure thread-safety.
• lib/concurrent/actor/core.rb — Actor model implementation providing message-passing concurrency; core to high-level concurrent patterns in the gem.
• Rakefile — Build, test, and release task definitions; essential for understanding CI/CD workflow and test execution patterns.

Add a new Executor type (e.g., custom thread pool)

1. Create a new executor class inheriting from lib/concurrent/executor/executor_service.rb and implement post, shutdown, kill, and wait_for_termination methods (lib/concurrent/executor/your_executor.rb)
2. Add the executor class to the public API in lib/concurrent-ruby.rb by requiring and exposing it (lib/concurrent-ruby.rb)
3. Write spec tests covering initialization, task submission, shutdown, and edge cases (spec/concurrent/executor/your_executor_spec.rb)
4. Update CHANGELOG.md with a note about the new executor (CHANGELOG.md)

Add a new concurrency utility (e.g., CountDownLatch, Semaphore variant)

1. Create the utility class using synchronization primitives from lib/concurrent/synchronization.rb; mix in ImmutableStruct if needed (lib/concurrent/your_utility.rb)
2. Expose the utility via the main gem file so it's available to users (lib/concurrent-ruby.rb)
3. Write comprehensive specs including threading tests and edge case handling (spec/concurrent/your_utility_spec.rb)
4. Add example usage to the docs-source directory if it's a notable addition (docs-source/your_utility.md)

Add an Actor-based example or extension

1. Create a new actor behavior by subclassing lib/concurrent/actor/core.rb or using define_method pattern from docs examples (examples/actor_example.rb)
2. If creating a reusable behavior mixin, place it in lib/concurrent/actor/ and require it in lib/concurrent-ruby.rb (lib/concurrent/actor/your_behavior.rb)
3. Add tests demonstrating actor lifecycle, message handling, and failure modes (spec/concurrent/actor/your_behavior_spec.rb)
4. Document the pattern in docs-source/actor/main.md with code examples (docs-source/actor/main.md)

Optimize or add a native C extension for a hot component

1. Create a C extension source file that wraps the Ruby implementation with faster primitives (ext/concurrent_ruby_ext/your_component.c)
2. Update concurrent-ruby-ext.gemspec to build and compile your extension (concurrent-ruby-ext.gemspec)
3. Add fallback pure-Ruby implementation in lib/concurrent/ that's used if extension fails to load (lib/concurrent/your_component.rb)
4. Run benchmarks from examples/ to verify performance improvement (examples/benchmark_your_component.rb)

• Pure Ruby with optional native C extensions (concurrent-ruby-ext) — Provides maximum portability across Ruby implementations (MRI, JRuby, TruffleRuby) while allowing opt-in performance via C for hot paths like atomics and synchronization.
• Actor model inspired by Erlang/Akka — Proven paradigm for building fault-tolerant, scalable systems; message-passing prevents shared-state concurrency bugs and naturally maps to distributed systems.
• Thread pools with configurable executors — Decouples task submission from execution strategy; allows users to tune concurrency for their hardware and workload without changing application code.
• Futures/Promises for composition — Enables declarative, composable async workflows that avoid callback hell and integrate with Ruby's iterator/enumerable patterns.

• Synchronous, blocking API over async/await keywords

  • Why: Ruby lacks native async/await; blocking futures are compatible with all Ruby versions and integrate naturally with existing code. JRuby and TruffleRuby can still achieve concurrency via OS threads.
  • Consequence: Users must explicitly block or chain callbacks; not zero-cost compared to language-level async but maximizes compatibility and simplicity.

• Shared mutable state (agents) in addition to immutable message-passing (actors)

  • Why: Covers diverse use cases: actors for fault tolerance and scale, agents for local shared state without distributed complexity.
  • Consequence: Increases API surface and cognitive load; users must choose the right tool for their problem (shared state vs. message-passing).

• Opt-in native extensions rather than requiring compilation

  • Why: Maximizes gem adoption and installation simplicity on all platforms.
  • Consequence: Performance-critical code may be 2–10x slower without C extensions; users deploying to resource-constrained environments may need to explicitly install extensions.

• Does not provide distributed actor systems; actors run only within a single process.
• Not a replacement for real-time guarantees; relies on OS scheduling and Ruby GIL behavior.
• Does not handle automatic load balancing or service discovery; users must manage executor pools and task distribution.
• Not a web framework; focuses purely on concurrency primitives, not HTTP routing or request handling.

C extensions (concurrent-ruby-ext) are optional—core works in pure Ruby but lacks atomic operations and lock-free structures; performance differs significantly between MRI/JRuby/TruffleRuby. Actors use Celluloid-inspired design (see docs-source/actor/celluloid_benchmark.rb) but are not Celluloid—don't mix APIs. Thread-safe guarantees depend on using provided abstractions; raw Thread usage voids guarantees. Some examples in docs-source/ are input templates (.in.rb) requiring processing—not directly runnable. Java extensions require JRuby; C extensions require native compiler + Ruby dev headers.

• Actor Model — Concurrent-ruby's actor system (lib/concurrent/actor/) is a primary feature for building fault-tolerant distributed systems; understanding actors and message passing is essential for using this library's most powerful patterns.
• Future/Promise Pattern — Futures and promises (lib/concurrent/future.rb, lib/concurrent/promise.rb) are foundational abstractions in this gem for handling deferred, asynchronous computations; nearly every async pattern in concurrent-ruby builds on them.
• Thread Pool / Executor — The executor framework (lib/concurrent/executor/) manages thread lifecycle and workload distribution; choosing the right executor (FixedThreadPool, CachedThreadPool, etc.) is critical for performance and resource management.
• Supervision Tree — Erlang-inspired supervision (docs-source/actor/supervision_tree.in.rb) enables fault recovery in actor systems; understanding parent-child actor hierarchies and restart strategies is key to building resilient concurrent applications.
• STM (Software Transactional Memory) / TVar — TVars (referenced in docs-source/images/tvar/) provide optimistic concurrency for shared mutable state without locks; this is a unique feature compared to simpler thread pools, enabling complex multi-variable atomic operations.
• Dataflow / Reactive Programming — Dataflow variables (docs-source/dataflow.md, docs-source/dataflow_top_stock_calc.md) enable constraint-based, reactive computation where results automatically propagate when dependencies resolve; useful for complex event coordination.
• Lock-Free Data Structures — The C/Java extensions in ext/ implement atomic operations and lock-free collections (esp. in JRuby); understanding lock-free vs. mutex-based synchronization is critical for high-performance concurrency.

• celluloid/celluloid — Predecessor actor model library that inspired concurrent-ruby's actor system design and supervision trees
• jruby/jruby — JRuby interpreter that concurrent-ruby optimizes for with native extensions and lock-free structures
• ruby/ruby — MRI/CRuby interpreter—primary target; concurrent-ruby works across MRI/JRuby/TruffleRuby but MRI is baseline
• EventMachine/eventmachine — Alternative Ruby concurrency library using reactor pattern; concurrent-ruby offers thread-based abstractions as complement/contrast
• ruby-concurrency/concurrent-ruby-ext — Separate gem providing JRuby/C extensions for atomic operations and lock-free data structures used by core concurrent-ruby

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive documentation for Channel API with runnable examples

The repo has partial Channel documentation (channel.in.md, channel.init.rb, channel.out.md) but the docs-source structure suggests incomplete examples. Channel is a complex concurrency primitive that needs detailed walkthroughs similar to the actor and promises documentation. This would help new users understand message passing patterns.

• [ ] Review existing docs-source/channel.* files to identify gaps in examples
• [ ] Create comprehensive channel.md documentation with multiple real-world scenarios (producer-consumer, work distribution, backpressure handling)
• [ ] Add 3-5 runnable example files (channel-basic.in.rb, channel-patterns.in.rb, channel-errors.in.rb) following the existing docs-source pattern
• [ ] Verify examples execute correctly and generate corresponding .out.rb files
• [ ] Update docs-source/signpost.md to link to Channel documentation properly

Add GitHub Actions workflow for Ruby version compatibility matrix testing

The repo has ci.yml and experimental.yml workflows but the file structure suggests no dedicated matrix testing across Ruby versions (2.7, 3.0, 3.1, 3.2, 3.3, etc.). With three gems (concurrent-ruby, concurrent-ruby-ext, concurrent-ruby-edge), testing against multiple Ruby versions is critical to catch version-specific concurrency bugs early.

• [ ] Review .github/workflows/ci.yml to understand current test setup
• [ ] Create new .github/workflows/ruby-matrix.yml with strategy matrix for Ruby versions 2.7 through 3.3
• [ ] Configure matrix to test concurrent-ruby-ext native extension compilation across versions
• [ ] Add JRuby and TruffleRuby as optional test targets
• [ ] Ensure Gemfile dependencies handle version-specific constraints (e.g., bundler, rake versions)

Add integration tests for Promise and Future chaining with error propagation

While futures.md and promises.md documentation exist, the file structure shows no dedicated test suite for complex chaining scenarios. Promise/Future error handling and chaining across multiple async operations is error-prone and needs comprehensive integration tests to prevent regressions.

• [ ] Create spec/concurrent/promises_futures_integration_spec.rb for complex chaining scenarios
• [ ] Add tests covering: promise chain with multiple rejections, future callbacks on error, mixed promise/future chains, timeout propagation, cancellation propagation
• [ ] Test edge cases: circular dependencies, deeply nested chains (10+ levels), rapid state transitions
• [ ] Verify all tests pass with both CRuby and JRuby (test against Rakefile and CI config)
• [ ] Add performance benchmarks in docs-source/ showing chain overhead for different nesting depths

• Add RSpec test coverage for edge cases in lib/concurrent/promise.rb (promise chaining, rejection handling, timeout scenarios)—many concurrency bugs hide in corner cases not exercised by current spec/concurrent/promise_spec.rb.
• Write an executable docs example in docs-source/ for the TVar (transactional variable) feature mentioned in docs-source/images/tvar/—expand TVar documentation and create a runnable docs-source/tvar.in.rb + .out.rb pair similar to existing actor examples.
• Document the performance characteristics of different Executor implementations (FixedThreadPool vs CachedThreadPool vs ImmediateExecutor) with benchmarks in a new docs-source/executor_benchmarks.md—currently missing direct comparison guidance for users choosing executors.

The concurrent-ruby library appears to be a well-maintained open-source concurrency framework with no critical security vulnerabilities evident from the static analysis of the file structure. The project follows standard Ruby gem practices with proper licensing (MIT), contribution guidelines, and CI/CD pipelines. Primary gaps are: (1) missing dependency vulnerability data for assessment, (2) lack of SECURITY.md policy file for vulnerability disclosure, and (3) documentation examples that should be reviewed for security best practices. The codebase itself focuses on concurrency primitives (actors, futures, promises, thread pools) and does not appear to have injection risks, hardcoded secrets, or infrastructure misconfiguration visible in the file listing. Recommended actions: enable Dependabot for automated dependency scanning, create security policy documentation, and conduct periodic security audits of example code patterns.

• Low · Incomplete Dependency Information — Gemfile, *.gemspec files. The dependency/package file content was not provided for analysis. Unable to assess for known vulnerable dependencies, outdated versions, or unvetted third-party packages. Fix: Provide dependency files (Gemfile, concurrent-ruby.gemspec, concurrent-ruby-edge.gemspec, concurrent-ruby-ext.gemspec) for vulnerability scanning using tools like Bundler-audit or Dependabot.
• Low · Missing Security Policy Documentation — Repository root. No SECURITY.md or security policy file was found in the repository. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file with clear instructions for reporting security vulnerabilities privately and responsibly.
• Low · Potential Code Execution in Documentation Examples — docs-source/, examples/. The codebase contains numerous example files with executable Ruby code in docs-source and examples directories. While documentation examples are expected to contain code, examples should be carefully reviewed to ensure they don't demonstrate insecure patterns. Fix: Review all example files to ensure they don't demonstrate anti-patterns like unsafe thread synchronization, race conditions, or insecure API usage. Add security notes where appropriate.
• Low · Limited Docker Security Configuration Visibility — Repository root / CI configuration. No Dockerfile or docker-compose files are visible in the file structure provided. If containerization is used for deployment, security configurations cannot be assessed. Fix: If Docker is used, provide Dockerfile and docker-compose files for review. Ensure base images are minimal, regularly updated, and from trusted sources.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.