ci: pin json 2 for Rails before 8.1

The compatibility matrix runs bundle lock --update. On October 3 it
still resolved json 2.21.2, because rubocop 1.88.2 and standard
1.56.0 held json below 3. rubocop 1.91.0 and standard 1.57.0 allow
json 3, so the matrix now resolves json 3.0.2, and every Rails 7.1,
7.2, and 8.0 job fails with "unknown keyword: quirks_mode". main
fails the same way today.

The break is in Active Support, not in Solid Objects. Local checks
with json 3.0.2 show that Active Support 7.1.6 and 8.0.5.1 fail to
encode and decode, 8.1.3.1 fails to decode, and only 8.1.4 works.
An application on those Rails lines must pin json 2.x, so the matrix
now pins it too and tests the configuration that the guide
prescribes. The Rails 7.1 suite passes with the pin: 873 runs, 0
failures.

Correct the json note in docs/operations.md, docs/agents.md, the
quickstart README, and context7.json. The earlier note named only the
8.1 releases before 8.1.4.

Author: cardmagic

CHANGELOG.md

@@ -26,10 +26,12 @@
   hold once. The check also fails when a `TicketSale` sample in the README or
   in `docs/` differs from the actor that it runs. A new `quickstart` CI job runs
   the check, and the release job waits for it.
-- Correct the `json` 3.0.2 note in `docs/operations.md`. Only Active Support
-  8.1.3.1 and earlier 8.1 releases fail with it; Active Support 8.1.4 decodes
-  correctly. Upgrade Rails, or pin `json` to 2.x when an upgrade is not
-  possible.
+- Correct the `json` 3.x note in `docs/operations.md`. The `json` gem 3.x works
+  only with Active Support 8.1.4 or newer. Active Support 7.1, 7.2, and 8.0
+  raise `unknown keyword: quirks_mode`, and Active Support 8.1.3.1 and earlier
+  8.1 releases fail to decode. Upgrade Rails to 8.1.4 or newer, or pin `json`
+  to 2.x. The compatibility CI matrix now pins `json` 2.x for Rails 7.1, 7.2,
+  and 8.0, the configuration that the guide prescribes.
 
 ## 0.17.0 - 2026-10-03
 

Gemfile

@@ -10,6 +10,7 @@ if rails_version
   %w[actioncable actionpack actionview activerecord activesupport railties].each do |library|
     gem library, constraint
   end
+  gem "json", "~> 2" if Gem::Version.new(rails_version) < Gem::Version.new("8.1")
 end
 
 group :development, :test do

context7.json

@@ -2,12 +2,24 @@
   "$schema": "https://context7.com/schema/context7.json",
   "projectTitle": "Solid Objects for Rails (solid_objects)",
   "description": "SQL-backed virtual actor library for Ruby on Rails. Actors have stable identities, durable JSON state in SQLite, PostgreSQL, or MySQL, ordered per-identity mailboxes, fenced activation, durable reminders, and transactional effects. Requires Ruby 3.3+ and Rails 7.1+.",
-  "folders": ["docs", "examples"],
-  "excludeFolders": ["./docs/adr", "./docs/research"],
-  "excludeFiles": ["AGENTS.md", "CLAUDE.md", "CONTRIBUTING.md", "implementation-plan.md"],
+  "folders": [
+    "docs",
+    "examples"
+  ],
+  "excludeFolders": [
+    "./docs/adr",
+    "./docs/research"
+  ],
+  "excludeFiles": [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "CONTRIBUTING.md",
+    "implementation-plan.md"
+  ],
   "rules": [
     "Solid Objects requires Rails 7.1 or newer and Ruby 3.3 or newer. It is a Rails engine, not a framework-independent Ruby library.",
     "Install with bundle add solid_objects, bin/rails generate solid_objects:install, bin/rails db:migrate, and bin/rails solid_objects:doctor.",
+    "The json gem 3.x works only with Active Support 8.1.4 or newer. On Rails 7.1, 7.2, 8.0, or 8.1 before 8.1.4, pin gem \"json\", \"~> 2\".",
     "The generated authorization policies deny every operation. Production policies must bind the actor type and ID to the authenticated user or tenant, and callers pass authorization_context:.",
     "Run bundle exec solid_objects start for reminders, async calls, effects, and broadcasts. Direct synchronous calls do not need it.",
     "Delivery is at least once. Effect handlers registered with SolidObjects.register_effect must use context.id as the idempotency key.",

docs/agents.md

@@ -64,11 +64,10 @@ bin/rails solid_objects:doctor
 The generator adds an initializer and copies migrations into the application.
 The doctor checks the configuration, the tables, and one real actor round trip.
 
-If the doctor or an actor call fails with
-`ArgumentError: wrong number of arguments (given 2, expected 1)` from
-`ActiveSupport::JSON.decode`, the application has Active Support 8.1.3.1 or
-earlier with `json` 3.0.2. Upgrade Rails to 8.1.4 or newer. If you cannot
-upgrade, pin `gem "json", "~> 2"` in the `Gemfile`.
+The `json` gem 3.x works only with Active Support 8.1.4 or newer. On Rails
+7.1, 7.2, 8.0, or 8.1 before 8.1.4, pin `gem "json", "~> 2"` in the
+`Gemfile`. Without the pin, Active Support raises an `ArgumentError`, such as
+`unknown keyword: quirks_mode`, for every JSON column.
 
 [Installing and upgrading](operations.md#installing-and-upgrading) has the
 details.
@@ -238,7 +237,7 @@ runs checks 2 and 4 against a new Rails application.
 | `SolidObjects::SyncTimeout` | The call did not finish in time. The message is still durable. Use its `message_reference` to wait for the result |
 | `SolidObjects::ApplicationWriteForbidden` | A handler wrote a model directly. Use `commit_action` or `emit` |
 | `SolidObjects::Rejected` | The actor called `reject`. This is a business result, not a retry |
-| `ArgumentError` from `ActiveSupport::JSON.decode` | Upgrade Rails to 8.1.4 or newer, or pin `gem "json", "~> 2"` |
+| `ArgumentError` from `ActiveSupport::JSON`, such as `unknown keyword: quirks_mode` | `json` 3.x with Active Support before 8.1.4. Upgrade Rails to 8.1.4 or newer, or pin `gem "json", "~> 2"` |
 
 ## 11. Guarantees to state correctly
 

docs/operations.md

@@ -26,18 +26,18 @@ reports a failed or warned check rather than raising out of the command.
 ## Installing and upgrading
 
 Solid Objects keeps actor state, message arguments, results, and the remembered
-idempotency keys in JSON columns. Active Support decodes every one of them.
-Active Support 8.1.3.1 and earlier 8.1 releases fail with the `json` gem at
-3.0.2. `ActiveSupport::JSON.decode` raises:
+idempotency keys in JSON columns. Active Support encodes and decodes every one
+of them. The `json` gem 3.x works only with Active Support 8.1.4 or newer:
 
-```
-ArgumentError: wrong number of arguments (given 2, expected 1)
-```
+- Active Support 7.1, 7.2, and 8.0 raise
+  `ArgumentError: unknown keyword: quirks_mode` when they encode or decode.
+- Active Support 8.1.3.1 and earlier 8.1 releases raise
+  `ArgumentError: wrong number of arguments (given 2, expected 1)` when they
+  decode.
 
 The failure is in Active Support rather than in Solid Objects, and it reaches
-every JSON column in a Rails application. Active Support 8.1.4 decodes
-correctly with `json` 3.0.2. Upgrade Rails to 8.1.4 or newer. If you cannot
-upgrade, pin the 2.x series of `json`:
+every JSON column in a Rails application. Upgrade Rails to 8.1.4 or newer. On
+an older Rails release, pin the 2.x series of `json`:
 
 ```ruby
 gem "json", "~> 2"

examples/quickstart/README.md

@@ -30,10 +30,10 @@ rails new ticket_demo
 cd ticket_demo
 ```
 
-Active Support 8.1.3.1 and the `json` gem 3.0.2 do not work together:
-`ActiveSupport::JSON.decode` raises an `ArgumentError`, and Solid Objects
-decodes its JSON columns with it. Active Support 8.1.4 does not have this
-problem. If `Gemfile.lock` shows both of the incompatible versions, read
+The `json` gem 3.x works only with Active Support 8.1.4 or newer. Solid
+Objects stores its state in JSON columns, so an older Active Support with
+`json` 3.x fails on every actor call. A new Rails application resolves Rails
+8.1.4 or newer, which works. For an older Rails application, read
 [Installing and upgrading](../../docs/operations.md#installing-and-upgrading)
 before you continue.