docs: name Solid Objects a virtual actor library

[cardmagic]

Why

An agent asked "does Ruby have a virtual actor library" answered no. The architecture guide already called Solid Objects a database-backed virtual actor runtime, but the README, the gem metadata, and the website did not use the category. A frozen baseline of 80 agent runs (two environments, 20 prompts, two runs each) found the project in 15 of 64 suitable runs before this change.

What changes

• The README opening, the gemspec summary, and the gemspec description name the category: a SQL-backed virtual actor library for Ruby on Rails.
• The gem homepage is https://solidobjects.dev/ruby. The old value, the site root, redirects to the Node page.
• docs/virtual-actors.md is the category guide. It gives the short answer, the definition, an example, fit and poor-fit criteria, comparisons with sources checked on October 7, 2026, and an Orleans concept map.
• docs/agents.md is a consumer guide for coding agents. It covers fit, package identity, installation, authorization, the runtime process, effect idempotency, verification, and troubleshooting.
• examples/quickstart/ and rake quickstart prove the published recipe against the built gem in a new Rails app. A new quickstart CI job runs it, and the release job now waits for it.
• context7.json limits Context7 indexing to the consumer documentation.
• docs/operations.md corrects the json 3.0.2 note. Only Active Support 8.1.3.1 and earlier fail; Active Support 8.1.4 decodes correctly.
• AGENTS.md adds the release step that refreshes the site snapshot and the Context7 index.

Effects

• API: none. Runtime code does not change.
• Correctness and security: none. The guides keep deny-by-default authorization and state at-least-once delivery, no cross-actor transactions, and pre-1.0 status. The quickstart grants only the message and query policies, for a local demo.
• Compatibility: the gem metadata changes on the next release.
• CI: the release job now depends on the quickstart job, which needs rubygems.org access.

How the quickstart proves the artifact

rake quickstart builds the gem, runs rails new --minimal --skip-bundle with SQLite, copies the built .gem into vendor/cache, and runs bundle install --local. It confirms that the Gemfile has no path:, that the Gemfile.lock checksum equals the built gem's SHA-256, and that the loaded solid_objects/version.rb is inside the temporary bundle path. It runs the generator, the migrations, and the doctor. Eight bin/rails runner processes hold the same event while solid_objects start runs, and exactly one hold commits. A due reminder waits while the runtime is stopped and releases the hold once after the restart. The check fails when a TicketSale sample in the README or docs/ differs from the actor that it runs.

Observed failures before the fixes

• test/unit/gem_specification_test.rb: Expected /virtual actors?/i to match "Cloudflare Durable Objects, ported to Rails". and expected "https://solidobjects.dev/ruby", actual "https://solidobjects.dev". The packaging test failed with to include "docs/agents.md" when the guide was moved aside.
• rake quickstart before the recipe existed: quickstart proof failed: examples/quickstart/README.md exists (QuickstartSmoke::Failure). Each key assertion was also shown to fail when its condition breaks: installing the published gem instead of the built one, skipping the restart, and leaving the runtime running.

Validation

• bundle exec rake: 873 runs, 3310 assertions, 0 failures, 0 errors, 28 skips (PostgreSQL and MySQL suites without a database URL). Standard, RuboCop, RBS, Steep, and Brakeman are clean.
• bundle exec rake quickstart: passed on Ruby 4.0.5 and Ruby 3.3.9 (local runs, not hosted CI).
• bundle exec rake build: the built gem contains docs/agents.md and docs/virtual-actors.md, and its metadata homepage is https://solidobjects.dev/ruby.
• git diff --check: clean.

Roadmap: no change. This changes documentation positioning and adds an onboarding proof. It does not change a runtime capability.

Release and CI fix

• chore: prepare version 0.17.1 moves the changelog into a dated 0.17.1 section.
• ci: pin json 2 for Rails before 8.1: the compatibility matrix now resolves json 3.0.2, because rubocop 1.91.0 and standard 1.57.0 no longer hold json below 3. With json 3.0.2, Active Support 7.1.6 and 8.0.5.1 fail to encode and decode (unknown keyword: quirks_mode), and only Active Support 8.1.4 works. main fails the same way today. The matrix now pins json 2.x for Rails 7.1, 7.2, and 8.0, the configuration that the guide now prescribes. The Rails 7.1 suite passes locally with the pin: 873 runs, 0 failures.

[greptile-apps]

Confidence Score: 5/5

[Medium risk] Rebrands the gem and adds documentation and a quickstart test.

The PR appears safe to merge; all three previous findings are fixed and no new blocking issue was found.

What we checked:

• CI applies the JSON pin: The compatibility job updates the lockfile before installing. Rails 7.1, 7.2, and 8.0 therefore receive the new json constraint.

Summary

Solid Objects is now described as a SQL-backed virtual actor library for Rails. The PR adds consumer guides, a clean-install quickstart, and a CI check required before release.

• All three previous findings are addressed.
• Older Rails compatibility jobs now pin json to 2.x.
• The version and changelog prepare release 0.17.1.
• No new actionable issues were found.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Build gem] --> B[Create temporary Rails app]
  B --> C[Install built gem locally]
  C --> D[Check checksum and loaded files]
  D --> E[Install tables and demo policies]
  E --> F[Check concurrent holds]
  F --> G[Stop runtime and wait for reminder]
  G --> H[Restart runtime and check recovery]
  H --> I[Release can proceed]

Loading

_{Reviews (2) · Last reviewed commit: "test: check that the transmission policy..." · Reviewed by Greptile}

[cardmagic]

@greptileai Please review the latest commit 9f11cdf. It answers all three findings: DENIED_POLICIES now includes authorize_transmission (rake quickstart fails with "authorize_transmission stays denied" when the template grants it), the two guards that cannot fire are gone, and both proof methods return Hash[Symbol, Integer]. The branch also adds 7d2202f, which pins json 2.x for the Rails 7.1, 7.2, and 8.0 compatibility jobs and documents the json 3 requirement, and 143297c, which prepares 0.17.1.