solid_objects 0.17.4 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d26650acca584b91a9933ee43ce1aeb310200d240994040a3ae8c8ea81dea1b
-  data.tar.gz: e97ad7100bd3822b005c571c2479ab833b65082ad0a249fd88c619a83da62980
+  metadata.gz: 11624a306bdeca71c5da082c39329f579c8d5d9b88945db2e49b534d2c317bc2
+  data.tar.gz: 7ac2b6c343b243169f92273179591db817a0e51c24e0312eaa59f8ee46c1e17f
 SHA512:
-  metadata.gz: c89b65cc0a103afb36bdc8570e55ab53adcd21fa59118d34291c2e174e9c0fc603cdf4c8c534a13acf21bcae54c6e3f1f54510635e89ff53d88b63f3ff09e7a2
-  data.tar.gz: '08a065d488f819ed054e8b57fd7bef8666be7c8c4dea41bd340cf07f8661c4570dd69d0a37a96c9f80c9a3fabcec6a6f691ab8d061c4e9293b1891da9da07cc4'
+  metadata.gz: dbf6ea115998afb97d759724469a29d8dfffa832ca52a6713027cbc5822d56ce2e40b55213deadefc598636beddeaebb49777e3e59d61a20b344a6b8bba1c670
+  data.tar.gz: 29e113dbdb487e5eaf3d9061dc494c6e6aaa54e2bf5fc2eba1bcd0e4a9db7684a1a7bffb65efc69cd0436d07c2b5e9523ab9075d8652f0c005affe545fd3d52e

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 1.0.0 - 2026-10-13
+
+- Version 1.0 freezes the public API under semantic versioning.
+  [docs/versioning.md](docs/versioning.md) gives the promise and its limits.
+  Version 1.0 is not a claim of measured scale: the benchmarks are
+  development measurements, and longer soak tests are open work.
+- **Breaking:** a turn that calls `schedule` and then calls no operation on the
+  result now fails with `SolidObjects::ScheduleWithoutOperation`. The runtime
+  does not retry that turn, and the message becomes a dead letter. Before this
+  release, such a call stored no reminder and gave no error. Correct code,
+  such as `schedule(at: time).expire`, does not change. The turn can keep the
+  result and call the operation later. A `schedule` call with no operation in
+  an observable fails the turn with `SolidObjects::QueryMutatedState`.
+  JavaScript has the same behavior.
+- `bin/rails solid_objects:doctor` has a new `json` check, and the boot prints
+  a warning, when Active Support cannot decode JSON with the installed `json`
+  gem. This is the case for `json` 3.x on Rails older than 8.1.4. The check
+  decodes one document and does not compare version numbers.
+- The gem summary and description now start with the problems that the gem
+  solves. The README has a status statement and names the projects that
+  Solid Objects is not.
+
+## 0.17.5 - 2026-10-12
+
+- Back off repeated interrupted-message recovery using `retry_delay`.
+  The first claimed attempt recovers immediately; after attempts 2, 3, 4,
+  and onward, the delay callback receives 1, 2, 3, and onward (defaults:
+  1, 2, 4 seconds, capped at 60 seconds). Total persisted claim attempts,
+  including earlier handler failures, determine the delay. The ready timestamp
+  survives worker replacement and preserves mailbox order while other actors
+  can proceed. Lease loss alone still does not dead-letter a message; handler
+  failure attempt limits, setting names, defaults, and schema stay unchanged.
+- Emit `activation.lost` with the message ID and total attempt count when a
+  turn loses its fence, including while saving a handler failure or rejection,
+  matching JavaScript instrumentation. Shutdown requested
+  by that callback stops the worker before another pass. Skip a cached actor
+  whose first message is delayed so later ready messages cannot starve peers.
+
+- Preserve caller lifecycle guarantees with regression tests for concurrent
+  synchronous calls retaining their staged effects and for caller process
+  re-registration after stale-process cleanup and retention. Both cases
+  already work in Ruby; no runtime behavior or configuration changes.
+  The concurrency test waits for the second caller's busy-actor wait before
+  allowing the first caller to commit its staged effect.
+
 ## 0.17.4 - 2026-10-12
 
 - Renew activations between turns in a drain pass when renewal is due,

data/README.md

@@ -11,6 +11,18 @@ stable identity, and its state lives in the SQL database that your app already
 uses. [Virtual actors in Ruby on Rails](docs/virtual-actors.md) explains the
 model and when to use it.
 
+**Status.** Version 1.0: the public API follows semantic versioning and does
+not break before 2.0. [Versioning](docs/versioning.md) gives the limits of the
+promise. First public release: August 6, 2026. One maintainer.
+
+**Production use.** One first-party application with more than 100,000 users
+runs it in production. That is a count of users, not a measure of load. No
+production use by other people is known. The [benchmarks](docs/benchmarks.md)
+are development measurements, and longer soak tests are open work.
+
+**It is not** Solid Queue, SolidJS, or the `service_actor` gem, and it is not
+affiliated with Rails or Cloudflare.
+
 In a shopping cart, paying twice at the same time is a big problem. The payment provider might time out, and your Rails site could be restarting before recovery finishes.
 
 To deal with this safely, you often need logic scattered between 7-10 files like database row locks, Redis locks, delayed jobs, retries, and cleanup code to keep that process straight. They are not all large, but they must agree about the same payment state and failure rules. That coordination is the difficult part.
@@ -193,9 +205,11 @@ explanations remain in `docs/`. The README stops here.
 
 ## Status and license
 
-Solid Objects Ruby is a pre-1.0 early release. Its correctness core is tested
-against SQLite, PostgreSQL, and MySQL, but the project makes no production-ready
-claim. That requires more hardening and operational soak evidence. Expect breaking changes.
+Version 1.0 promises a stable public API. Its correctness core is tested
+against SQLite, PostgreSQL, and MySQL. It makes no claim of measured scale:
+the [benchmarks](docs/benchmarks.md) are development measurements, and longer
+soak tests are open work. [Versioning](docs/versioning.md) says what a release
+can change.
 
 Solid Objects is released under the [MIT License](MIT-LICENSE). It is an
 independent project and is not affiliated with, sponsored by, or endorsed by

data/docs/agents.md

@@ -69,18 +69,22 @@ 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.
+The doctor checks the `json` gem, the configuration, the tables, and one real
+actor round trip.
 
-Install the current release. `bundle add solid_objects` selects it. Do not pin
-a version that you remember from earlier work; the API changed between
-releases. The current version is on <https://rubygems.org/gems/solid_objects>.
+Install the current release. `bundle add solid_objects` selects it. Do not use
+an API that you remember from a 0.x release; the API changed between 0.x
+releases. From version 1.0, the public API follows
+[semantic versioning](versioning.md). The current version is on
+<https://rubygems.org/gems/solid_objects>.
 
 The generated policies deny every call. Do step 5 before you call an actor.
 
 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.
+`unknown keyword: quirks_mode`, for every JSON column. The doctor reports this
+problem as a failure of its `json` check, and the boot prints a warning.
 
 [Installing and upgrading](operations.md#installing-and-upgrading) has the
 details.
@@ -173,6 +177,9 @@ Obey these rules in actor code:
   write in the same database.
 - Do not call an external API in a handler. Use `emit` and an effect handler.
 - Write each handler so that it can run again. Delivery is at least once.
+- Repeated lease losses back off but do not become dead letters. Observe
+  `activation.lost` and set an application stopping policy if a hard bound is
+  required; increasing the handler-failure attempt limit does not bound lease loss.
 - A reminder changes state only when it runs, and it runs only while
   `solid_objects start` runs. Do not compute expiry from the clock in a query;
   read the state that the reminder committed.
@@ -181,7 +188,7 @@ Avoid these mistakes:
 
 | Mistake | Correct form |
 | --- | --- |
-| `schedule(at: deadline)` with no operation after it | `schedule(at: deadline, key: buyer).expire(buyer:)`. `schedule` stages a reminder only when you call an operation on its result |
+| `schedule(at: deadline)` with no operation after it | `schedule(at: deadline, key: buyer).expire(buyer:)`. A `schedule` call with no operation after it fails the turn with `SolidObjects::ScheduleWithoutOperation` |
 | `reject "room full"` | `reject(:room_full, "The room is full")` |
 | `id` inside an actor | `actor_id`. An actor has no `id` method |
 | `register_effect(:name) { \|context, arguments\| ... }` | `register_effect(:name) { \|arguments, context\| ... }`. The arguments come first |
@@ -275,6 +282,7 @@ When you explain Solid Objects to a user, state these limits:
 - There are no transactions across actor identities.
 - Fencing stops a stale activation from a commit, but its code can continue to
   run.
-- The gem is pre-1.0 and makes no production-ready claim.
+- Version 1.0 promises a stable public API. It makes no claim of measured scale,
+  and no production use by other people is known.
 
 The [correctness contract](correctness.md) is the source for each guarantee.

data/docs/guides/expiring-reservations.md

@@ -164,7 +164,7 @@ See [the transactional outbox guide](transactional-outbox.md).
 - Delivery is at least once. Each operation must be safe to run again.
 - There are no transactions across actors. A reservation that spans two shows needs its own design.
 - One busy show runs its calls one at a time. Many shows run at the same time.
-- The gem is pre-1.0 and makes no production-ready claim.
+- Version 1.0 promises a stable public API. It makes no claim of measured scale.
 
 ## More information
 

data/docs/guides/ordered-jobs.md

@@ -221,7 +221,7 @@ You do not assign sequence numbers. The actor mailbox gives the order.
 - Delivery is at least once. Each operation must be safe to run again.
 - The gem provides no transactions across actors. A transfer between two accounts needs its own design, for example one SQL transaction on normal tables.
 - One busy account runs its entries one at a time.
-- The gem is pre-1.0 and makes no production-ready claim.
+- Version 1.0 promises a stable public API. It makes no claim of measured scale.
 
 ## More information
 

data/docs/guides/race-conditions.md

@@ -224,7 +224,7 @@ Delivery is at least once, so an effect can run more than once. See [effect idem
 - Delivery is at least once, not exactly once. Write each operation so that it can run again.
 - There are no transactions across actors. A change that must touch two events atomically needs one SQL transaction on normal tables.
 - One busy event runs its calls one at a time. Many events can run at the same time.
-- The gem is pre-1.0 and makes no production-ready claim.
+- Version 1.0 promises a stable public API. It makes no claim of measured scale.
 
 ## More information
 

data/docs/guides/transactional-outbox.md

@@ -145,7 +145,7 @@ One successful turn commits the actor state, the staged effects, the same-databa
 - Solid Objects requires Ruby 3.3 or newer and Rails 7.1 or newer.
 - Delivery is at least once. Each effect handler must deduplicate with `context.id`.
 - Solid Objects provides no transactions across actors.
-- The gem is pre-1.0 and makes no production-ready claim.
+- Version 1.0 promises a stable public API. It makes no claim of measured scale.
 
 ## More information
 

data/docs/observability.md

@@ -45,6 +45,7 @@ JavaScript does not await exporters. Telemetry is not a durable audit trail.
 | ------------------------------------------- | ---------------------------------------------------------------------------- |
 | `activation.started/completed/failed`       | Local actor activation hook lifecycle                                        |
 | `message.started/completed/failed/rejected` | One attempt's execution outcome                                              |
+| `activation.lost`                         | A message turn lost its activation fence; includes message ID and total attempt count |
 | `message.retry`                             | Failed attempt durably queued for another attempt                            |
 | `dead_letter.created`                       | Message exhausted retries or failed permanently                              |
 | `commit_action.started/completed/failed`    | One registered commit action inside the commit transaction                   |

data/docs/operations.md

@@ -43,6 +43,11 @@ an older Rails release, pin the 2.x series of `json`:
 gem "json", "~> 2"
 ```
 
+`bin/rails solid_objects:doctor` reports this problem as a failure of its
+`json` check, and the boot prints a warning that starts with
+`[solid_objects]`. Both decode one JSON document with Active Support. They do
+not compare version numbers.
+
 Review [CHANGELOG.md](../CHANGELOG.md) for compatibility and deployment-order
 notes, then update the gem:
 
@@ -606,3 +611,24 @@ heartbeat cleanup.
 Back up actor tables with the same consistency guarantees as application data.
 Restoring only instances without their mailboxes/outboxes, or vice versa, can
 violate application expectations.
+
+## Interrupted-message recovery
+
+An interrupted first claimed attempt recovers immediately. Recovery after
+persisted attempts 2, 3, 4, ... calls `retry_delay` with 1, 2, 3, ... . The
+callback returns seconds; defaults grow from 1 to 2 to 4 seconds up to 60 seconds.
+This uses total claim attempts, including earlier handler failures, not a
+separate lease-loss counter. The delay is stored in ready-message availability
+when a stale claim is recovered, survives worker replacement, and keeps later
+messages behind that message. Other actors can still run. Custom delays,
+including zero, remain authoritative.
+
+Lease loss alone does not create a dead letter, even with `max_attempts: 1`.
+Handler failures still use the full attempt count for `max_attempts` and
+`retry_delay`. An always-losing message remains pending indefinitely. Observe
+`activation.lost` (message ID and total attempt count) and impose an application
+stopping policy if a hard bound is required. Calling `request_shutdown` from
+instrumentation stops the worker before its next pass. Ruby uses a separate
+renewal thread and waits after lost turns; it does not have the JavaScript
+microtask starvation pattern. A handler must still return before its worker
+can finish shutting down.

data/docs/reminders.md

@@ -16,6 +16,26 @@ end
 Use `missed: :latest` to coalesce missed occurrences or `missed: :all` to
 enqueue each one.
 
+## A schedule call needs an operation
+
+`schedule` returns an object, and the reminder exists only after you call an
+operation on that object. A turn that calls `schedule` and then calls no
+operation on the result fails with `SolidObjects::ScheduleWithoutOperation`.
+The runtime does not retry that turn, and the message becomes a dead letter.
+
+```ruby
+# Wrong. The turn fails.
+schedule(at: 10.minutes.from_now, key: buyer)
+
+# Correct.
+schedule(at: 10.minutes.from_now, key: buyer).expire(buyer:)
+```
+
+You can keep the result and call the operation later in the same turn.
+
+An observable cannot call `schedule`, with or without an operation. The turn
+that reads the observable fails with `SolidObjects::QueryMutatedState`.
+
 ## A reminder is one named alarm per actor
 
 The uniqueness key is `(actor, reminder name)`. Scheduling a name that is

data/docs/roadmap.md

@@ -9,6 +9,17 @@
   [observability](observability.md).
 
 - Rails engine, install generator, migration, and CLI
+- A stable public API from version 1.0, with the limits in
+  [versioning](versioning.md)
+- A turn that calls `schedule` and then calls no operation on the result fails
+  with `ScheduleWithoutOperation`, which is not retried, matching JavaScript.
+  Before 1.0 such a call stored no reminder and gave no error. The projection
+  guard counts such a call in an observable as staged work, so that turn fails
+  with `QueryMutatedState`.
+- A `json` check in `solid_objects:doctor` and a warning during the boot, for
+  the `json` gem 3.x on an Active Support release that cannot decode with it.
+  The check decodes one document and does not compare version numbers. This
+  surface is Rails-only.
 - Explicit actor registry, references, JSON state, and state migrations
 - Queries, observable projections, and personalized payloads reject state mutation
   and staged durable work with `QueryMutatedState`, matching JavaScript. Query
@@ -25,7 +36,12 @@
   repeatable read. The tests count statements, and do not measure latency.
 - Activation leases, renewal between turns as well as in the renewal thread,
   unique activation tokens, generations, and
-  fenced commits
+  fenced commits. Interrupted first attempts recover immediately; repeated
+  interruptions use durable retry delays from total claim attempts minus one,
+  preserving mailbox order and progress for other actors. Lease loss emits
+  `activation.lost` with the message ID and attempt, including losses while
+  saving a handler failure or rejection. There is no hard retry cap;
+  applications needing one must impose a stopping policy.
 - Bounded activation passes, idle cache, hot-actor yield, and process records
 - At-least-once retries, terminal domain rejection, strict poison ordering,
   dead letters, and tail retry
@@ -240,5 +256,6 @@
    latency, query counts, and the three reactive delivery paths are measured on
    SQLite; adapter-specific and end-to-end browser measurements are not.
 
-No production-ready claim should be made until these hardening milestones have
-operational soak evidence.
+Version 1.0 freezes the public API under [semantic versioning](versioning.md).
+It does not complete these hardening milestones. The project makes no claim of
+measured scale until they have operational soak evidence.

data/docs/versioning.md

@@ -0,0 +1,50 @@
+# Versioning
+
+From version 1.0.0, Solid Objects follows
+[Semantic Versioning](https://semver.org/).
+
+## The promise
+
+The public API is the set of classes, methods, generators, commands, and
+configuration options that `README.md` and the files in `docs/` describe.
+
+| Release | What it can change |
+| --- | --- |
+| Patch, for example 1.0.1 | Corrections of defects. No new behavior |
+| Minor, for example 1.1.0 | New behavior. Code that uses the public API continues to work |
+| Major, for example 2.0.0 | A change that breaks code that uses the public API |
+
+## Supported versions
+
+A minor release can raise the minimum version of Ruby, Rails, SQLite,
+PostgreSQL, or MySQL. It does this only for a version that its own project no
+longer supports, and `CHANGELOG.md` names the change. A patch release does not
+raise a minimum version.
+[Compatibility and maturity](virtual-actors.md#compatibility-and-maturity)
+lists the current minimum versions.
+
+## Outside the promise
+
+- Classes, methods, and constants that the documentation does not describe.
+- The database schema. A minor release can add tables, columns, and indexes,
+  and it supplies a migration for each change.
+  [Installing and upgrading](operations.md#installing-and-upgrading) gives the
+  steps.
+- The text of error messages and log lines. The error classes are part of the
+  public API.
+- The timing of background work, where no configuration option sets it.
+- A correction of behavior that is different from the
+  [correctness contract](correctness.md). A patch release can make such a
+  correction.
+
+## What version 1.0 does not claim
+
+Version 1.0 is a promise about the API. It is not a claim of measured scale.
+The [benchmarks](benchmarks.md) are development measurements and do not
+guarantee capacity. Longer soak tests are open work. The project has one
+maintainer, and no production use by other people is known.
+
+## Releases before 1.0
+
+The 0.x releases changed the API between minor versions. `CHANGELOG.md` lists
+each change.

data/docs/virtual-actors.md

@@ -12,7 +12,8 @@ State and mailboxes live in the SQLite, PostgreSQL, or MySQL database that the
 Rails application already uses. Redis and a separate actor service are not
 necessary.
 
-Solid Objects is a pre-1.0 release. It makes no production-ready claim. Read
+Solid Objects 1.0 promises a stable public API. It makes no claim of measured
+scale. Read
 [Compatibility and maturity](#compatibility-and-maturity) before you choose it.
 
 ## What a virtual actor is
@@ -170,6 +171,10 @@ again without harm.
   a crash or a lost lease.
 - Ordered turns do not cancel stale Ruby code. Fencing stops a stale activation
   from a commit, but that code can continue to run.
+- An interrupted first attempt recovers immediately. Repeated interruptions
+  use growing, durable retry delays while keeping mailbox order. Lease loss
+  alone has no attempt limit; use instrumentation and an application stopping
+  policy when a hard bound is required.
 - External effects can run more than once. Use the stable effect ID, or
   another durable key, as the idempotency key at the provider.
 - There are no transactions across actor identities, and there is no replay of
@@ -194,9 +199,9 @@ matrix.
   InnoDB. MySQL works through `mysql2` or `trilogy`.
 - SQLite is correct for the same contract, but it is best for development and
   modest single-host workloads.
-- Pre-1.0. Expect changes that break compatibility. The correctness core has tests against all
-  three databases. The project has no production-ready claim and no measured
-  scale claim.
+- Version 1.0: the public API follows [semantic versioning](versioning.md). The
+  correctness core has tests against all three databases. The project makes no
+  claim of measured scale, and no production use by other people is known.
 
 The [roadmap](roadmap.md) records what is tested, what is partial, and what is
 next. For TypeScript and Node.js, use the

data/lib/solid_objects/activation.rb

@@ -52,7 +52,8 @@ module SolidObjects
     # @rbs () -> bool
     def ready?
       now = SolidObjects.database_adapter.database_now
-      ReadyMessage.where(instance_id: lease.instance_id, available_at: ..now).exists? ||
+      ready_message = ReadyMessage.where(instance_id: lease.instance_id).order(:sequence).first
+      (ready_message && ready_message.available_at <= now) ||
         ClaimedMessage.where(
           instance_id: lease.instance_id,
           process_id: lease.owner_id,
@@ -227,11 +228,12 @@ module SolidObjects
       claimed_message.destroy!
       return if message.completed? || message.dead?
 
+      delay = (message.attempt_count <= 1) ? 0 : SolidObjects.configuration.retry_delay.call(message.attempt_count - 1)
       ReadyMessage.create!(
         message:,
         instance:,
         sequence: message.sequence,
-        available_at: SolidObjects.database_adapter.database_now
+        available_at: SolidObjects.database_adapter.database_now + delay
       )
     end
 

data/lib/solid_objects/actor.rb

@@ -13,6 +13,7 @@ module SolidObjects
     REMINDER_HANDLE_KEY = "reminder_name"
 
     ReminderIntent = Data.define(:name, :operation, :at, :arguments, :interval_seconds, :missed_policy)
+    ScheduleCall = Data.define(:at, :key)
     UnscheduleIntent = Data.define(:name)
     UnscheduleAllIntent = Data.define(:operation)
     ReminderStatus = Data.define(:name, :operation, :key, :next_run_at, :interval_seconds,
@@ -154,6 +155,7 @@ module SolidObjects
     # @rbs @effect_recovery_intents: Array[EffectRecoveryIntent]
     # @rbs @commit_action_intents: Array[CommitActionIntent]
     # @rbs @reminder_intents: Array[ReminderIntent]
+    # @rbs @open_schedule_calls: Array[ScheduleCall]
     # @rbs @outbound_message_intents: Array[OutboundMessageIntent]
 
     attr_reader :actor_id, :state
@@ -167,6 +169,7 @@ module SolidObjects
       @effect_recovery_intents = []
       @commit_action_intents = []
       @reminder_intents = []
+      @open_schedule_calls = []
       @outbound_message_intents = []
     end
 
@@ -257,11 +260,14 @@ module SolidObjects
         raise ArgumentError, "missed reminder policy must be all or latest"
       end
       reminder_key = validated_reminder_key(key)
+      call = ScheduleCall.new(at:, key: reminder_key)
+      open_schedule_calls << call
 
       OperationDispatcher.new(
         actor_type: self.class.actor_type,
         handlers: self.class.definition.messages
       ) do |operation, arguments|
+        open_schedule_calls.delete_if { |open_call| open_call.equal?(call) }
         name = reminder_name(operation:, key: reminder_key)
         reminder_intents << ReminderIntent.new(
           name:,
@@ -537,6 +543,18 @@ module SolidObjects
       commit_action_intents.clear
       reminder_intents.clear
       outbound_message_intents.clear
+      open_schedule_calls.clear
+    end
+
+    # @rbs () -> void
+    def ensure_schedule_calls_have_operations!
+      call = open_schedule_calls.first
+      return unless call
+
+      arguments = [ "at: #{call.at.inspect}", ("key: #{call.key.inspect}" if call.key) ].compact.join(", ")
+      raise ScheduleWithoutOperation,
+        "schedule(#{arguments}) has no operation after it, so it stores no reminder. " \
+        "Call an operation on the result, for example schedule(at: time).expire"
     end
 
     # @rbs () -> Integer
@@ -563,11 +581,19 @@ module SolidObjects
       :effect_recovery_intents,
       :commit_action_intents,
       :reminder_intents,
-      :outbound_message_intents
+      :outbound_message_intents,
+      :open_schedule_calls
 
     # @rbs () -> Array[Array[Hash[Symbol, Object]]]
     def intent_snapshot
-      [ effect_intents, effect_recovery_intents, commit_action_intents, reminder_intents, outbound_message_intents ].map do |intents|
+      [
+        effect_intents,
+        effect_recovery_intents,
+        commit_action_intents,
+        reminder_intents,
+        outbound_message_intents,
+        open_schedule_calls
+      ].map do |intents|
         intents.map { |intent| intent.to_h.deep_dup }
       end
     end

data/lib/solid_objects/doctor.rb

@@ -99,14 +99,17 @@ module SolidObjects
 
     # @rbs @connection: untyped
     # @rbs @configuration: Configuration
+    # @rbs @json_compatibility: JsonCompatibility
 
-    # @rbs (?connection: untyped, ?configuration: Configuration) -> void
+    # @rbs (?connection: untyped, ?configuration: Configuration, ?json_compatibility: JsonCompatibility) -> void
     def initialize(
       connection: SolidObjects::Record.connection,
-      configuration: SolidObjects.configuration
+      configuration: SolidObjects.configuration,
+      json_compatibility: JsonCompatibility.new
     )
       @connection = connection
       @configuration = configuration
+      @json_compatibility = json_compatibility
     end
 
     # @rbs () -> Report
@@ -114,6 +117,7 @@ module SolidObjects
       configuration_check = check_configuration
       schema_check = check_schema
       checks = [
+        check_json,
         configuration_check,
         schema_check,
         check_authorization,
@@ -129,7 +133,15 @@ module SolidObjects
 
     private
 
-    attr_reader :connection, :configuration
+    attr_reader :connection, :configuration, :json_compatibility
+
+    # @rbs () -> Check
+    def check_json
+      problem = json_compatibility.problem
+      return fail_check(:json, problem) if problem
+
+      pass(:json, "Active Support decodes JSON with the json gem #{JSON::VERSION}")
+    end
 
     # @rbs () -> Check
     def check_configuration

data/lib/solid_objects/engine.rb

@@ -15,6 +15,10 @@ module SolidObjects
       SolidObjects::LogSubscriber.install
     end
 
+    initializer "solid_objects.json_compatibility" do
+      JsonCompatibility.new.warn_about_problem
+    end
+
     initializer "solid_objects.actors" do |application|
       application.config.to_prepare { ApplicationActorLoader.new.call }
     end

data/lib/solid_objects/errors.rb

@@ -10,6 +10,9 @@ module SolidObjects
   class QueryMutatedState < NonRetryableError
   end
 
+  class ScheduleWithoutOperation < NonRetryableError
+  end
+
   class UnsupportedDatabase < Error
   end
 

data/lib/solid_objects/executor.rb

@@ -16,6 +16,18 @@ module SolidObjects
 
     # @rbs () -> bool
     def call
+      execute
+    rescue LostActivation
+      SolidObjects.instrument(:"activation.lost", **instrumentation_payload, duration_milliseconds: elapsed_milliseconds)
+      raise
+    end
+
+    private
+
+    attr_reader :activation, :message
+
+    # @rbs () -> bool
+    def execute
       state_before = actor.state.to_h
       observables_before = actor.observable_values
       message_context = MessageContext.new(
@@ -29,6 +41,7 @@ module SolidObjects
       SolidObjects.instrument(:"recovery.reclaimed", **instrumentation_payload) if message.attempt_count > 1 && message.error.nil?
       SolidObjects.instrument(:"message.started", **instrumentation_payload)
       result = invoke_actor(message_context)
+      actor.ensure_schedule_calls_have_operations!
       observable_changes = changed_observables(observables_before, actor.observable_values)
       state_after = actor.state.to_h_with_byte_size
       ensure_query_is_read_only!(state_before, state_after.value)
@@ -53,10 +66,6 @@ module SolidObjects
       false
     end
 
-    private
-
-    attr_reader :activation, :message
-
     # @rbs () -> Actor
     def actor
       activation.actor

data/lib/solid_objects/json_compatibility.rb

@@ -0,0 +1,36 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class JsonCompatibility
+    PROBE = '{"probe":1}'
+
+    # @rbs @decode: ^(String) -> untyped
+
+    # @rbs (?decode: ^(String) -> untyped) -> void
+    def initialize(decode: ActiveSupport::JSON.method(:decode))
+      @decode = decode
+    end
+
+    # @rbs () -> String?
+    def problem
+      decode.call(PROBE)
+      nil
+    rescue ArgumentError => error
+      "Active Support #{ActiveSupport.version} cannot decode JSON with the json gem #{JSON::VERSION} " \
+        "(#{error.message}). Add gem \"json\", \"~> 2\" to the Gemfile, " \
+        "or use a Rails release that supports json 3"
+    end
+
+    # @rbs () -> void
+    def warn_about_problem
+      message = problem
+      return unless message
+
+      warn "[solid_objects] #{message}"
+    end
+
+    private
+
+    attr_reader :decode
+  end
+end

data/lib/solid_objects/version.rb

@@ -1,5 +1,5 @@
 # rbs_inline: enabled
 
 module SolidObjects
-  VERSION = "0.17.4"
+  VERSION = "1.0.0"
 end

data/lib/solid_objects.rb

@@ -20,6 +20,7 @@ require "solid_objects/telemetry"
 require "solid_objects/diagnostics"
 require "solid_objects/log_subscriber"
 require "solid_objects/serialization"
+require "solid_objects/json_compatibility"
 require "solid_objects/context"
 require "solid_objects/actor_registry"
 require "solid_objects/state"

data/sig/generated/lib/solid_objects/actor.rbs

@@ -81,6 +81,19 @@ module SolidObjects
       def members: () -> [ :name, :operation, :at, :arguments, :interval_seconds, :missed_policy ]
     end
 
+    class ScheduleCall < Data
+      attr_reader at(): untyped
+
+      attr_reader key(): untyped
+
+      def self.new: (untyped at, untyped key) -> instance
+                  | (at: untyped, key: untyped) -> instance
+
+      def self.members: () -> [ :at, :key ]
+
+      def members: () -> [ :at, :key ]
+    end
+
     class UnscheduleIntent < Data
       attr_reader name(): untyped
 
@@ -207,6 +220,8 @@ module SolidObjects
 
     @outbound_message_intents: Array[OutboundMessageIntent]
 
+    @open_schedule_calls: Array[ScheduleCall]
+
     @reminder_intents: Array[ReminderIntent]
 
     @commit_action_intents: Array[CommitActionIntent]
@@ -348,6 +363,9 @@ module SolidObjects
     # @rbs () -> void
     def discard_intents: () -> void
 
+    # @rbs () -> void
+    def ensure_schedule_calls_have_operations!: () -> void
+
     # @rbs () -> Integer
     def intent_count: () -> Integer
 
@@ -366,6 +384,8 @@ module SolidObjects
 
     attr_reader outbound_message_intents: untyped
 
+    attr_reader open_schedule_calls: untyped
+
     # @rbs () -> Array[Array[Hash[Symbol, Object]]]
     def intent_snapshot: () -> Array[Array[Hash[Symbol, Object]]]
 

data/sig/generated/lib/solid_objects/doctor.rbs

@@ -47,12 +47,14 @@ module SolidObjects
       def ping: (value: String) -> String
     end
 
+    @json_compatibility: JsonCompatibility
+
     @configuration: Configuration
 
     @connection: untyped
 
-    # @rbs (?connection: untyped, ?configuration: Configuration) -> void
-    def initialize: (?connection: untyped, ?configuration: Configuration) -> void
+    # @rbs (?connection: untyped, ?configuration: Configuration, ?json_compatibility: JsonCompatibility) -> void
+    def initialize: (?connection: untyped, ?configuration: Configuration, ?json_compatibility: JsonCompatibility) -> void
 
     # @rbs () -> Report
     def call: () -> Report
@@ -63,6 +65,11 @@ module SolidObjects
 
     attr_reader configuration: untyped
 
+    attr_reader json_compatibility: untyped
+
+    # @rbs () -> Check
+    def check_json: () -> Check
+
     # @rbs () -> Check
     def check_configuration: () -> Check
 

data/sig/generated/lib/solid_objects/errors.rbs

@@ -10,6 +10,9 @@ module SolidObjects
   class QueryMutatedState < NonRetryableError
   end
 
+  class ScheduleWithoutOperation < NonRetryableError
+  end
+
   class UnsupportedDatabase < Error
   end
 

data/sig/generated/lib/solid_objects/executor.rbs

@@ -22,6 +22,9 @@ module SolidObjects
 
     attr_reader message: untyped
 
+    # @rbs () -> bool
+    def execute: () -> bool
+
     # @rbs () -> Actor
     def actor: () -> Actor
 

data/sig/generated/lib/solid_objects/json_compatibility.rbs

@@ -0,0 +1,22 @@
+# Generated from lib/solid_objects/json_compatibility.rb with RBS::Inline
+
+module SolidObjects
+  class JsonCompatibility
+    PROBE: ::String
+
+    @decode: ^(String) -> untyped
+
+    # @rbs (?decode: ^(String) -> untyped) -> void
+    def initialize: (?decode: ^(String) -> untyped) -> void
+
+    # @rbs () -> String?
+    def problem: () -> String?
+
+    # @rbs () -> void
+    def warn_about_problem: () -> void
+
+    private
+
+    attr_reader decode: untyped
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.17.4
+  version: 1.0.0
 platform: ruby
 authors:
 - Lucas Carlson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-12 00:00:00.000000000 Z
+date: 2026-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable
@@ -276,12 +276,13 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.7'
-description: 'Solid Objects is a SQL-backed virtual actor library for Ruby on Rails,
-  with durable state, ordered operations, and automatic activation. It brings the
-  Cloudflare Durable Objects programming model to Rails: addressable objects with
-  ordered mailboxes, fenced activation, per-object reminders, transactional effects,
-  and reactive ERB. It runs on MySQL, PostgreSQL, and SQLite without Redis, and requires
-  Ruby 3.3 or newer and Rails 7.1 or newer.'
+description: 'Fix race conditions on one record in Rails: ordered operations, expiring
+  holds, and durable state in your existing SQL database. Solid Objects is a SQL-backed
+  virtual actor library for Ruby on Rails. It brings the Cloudflare Durable Objects
+  programming model to Rails: addressable objects with ordered mailboxes, fenced activation,
+  per-object reminders, transactional effects, and reactive ERB. It runs on MySQL,
+  PostgreSQL, and SQLite without Redis, and requires Ruby 3.3 or newer and Rails 7.1
+  or newer.'
 email:
 executables:
 - solid_objects
@@ -378,6 +379,7 @@ files:
 - docs/security.md
 - docs/state-migrations.md
 - docs/transmission.md
+- docs/versioning.md
 - docs/virtual-actors.md
 - examples/application/README.md
 - examples/application/app/actors/chat_room_actor.rb
@@ -464,6 +466,7 @@ files:
 - lib/solid_objects/executor.rb
 - lib/solid_objects/instance_pruner.rb
 - lib/solid_objects/instrumentation.rb
+- lib/solid_objects/json_compatibility.rb
 - lib/solid_objects/lease.rb
 - lib/solid_objects/lease_renewer.rb
 - lib/solid_objects/log_subscriber.rb
@@ -569,6 +572,7 @@ files:
 - sig/generated/lib/solid_objects/executor.rbs
 - sig/generated/lib/solid_objects/instance_pruner.rbs
 - sig/generated/lib/solid_objects/instrumentation.rbs
+- sig/generated/lib/solid_objects/json_compatibility.rbs
 - sig/generated/lib/solid_objects/lease.rbs
 - sig/generated/lib/solid_objects/lease_renewer.rbs
 - sig/generated/lib/solid_objects/log_subscriber.rbs
@@ -685,5 +689,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: SQL-backed virtual actors for Ruby on Rails
+summary: Fix race conditions on one record in Rails with SQL-backed virtual actors
 test_files: []