solid_objects 0.14.1 → 0.14.3

data/docs/reminders.md

@@ -0,0 +1,112 @@
+# Reminders
+
+Reminders are Solid Objects' durable equivalent of the Durable Objects Alarms
+API. One-shot and recurring alarms are actor-owned database records:
+
+```ruby
+def schedule_evaluation
+  schedule(
+    at: 1.hour.from_now,
+    every: 1.hour,
+    missed: :latest
+  ).evaluate(account_id:)
+end
+```
+
+Use `missed: :latest` to coalesce missed occurrences or `missed: :all` to
+enqueue each one.
+
+## A reminder is one named alarm per actor
+
+The uniqueness key is `(actor, reminder name)`. Scheduling a name that is
+already armed **moves the existing alarm** rather than adding a second one. The
+database enforces this with a unique index on `(instance_id, name)`.
+
+This is the same model as Orleans reminders and Durable Objects alarms. It
+makes a reminder safe to re-arm from a handler that may run more than once.
+Without a key the name is the operation, so this is a data-loss bug:
+
+```ruby
+# Wrong. Every entry overwrites the previous entry's alarm.
+def add(entry:)
+  self.entries = entries + [ entry ]
+  schedule(at: entry.fetch("wait_until")).deliver
+end
+```
+
+Two entries leave one reminder. The earlier wake-up never happens, nothing
+raises, and nothing is logged except a `solid_objects.reminder.replaced` event.
+
+## An alarm per item, with `key:`
+
+Pass `key:` when an actor is waiting on several things at once. The key is your
+own identifier for the item, and it names that item's alarm, so each item gets
+one:
+
+```ruby
+def add(entry:)
+  self.entries = entries + [ entry ]
+  schedule(at: entry.fetch("wait_until"), key: entry.fetch("id")).deliver
+end
+```
+
+Two entries now leave two reminders. Scheduling the same key again moves that
+item's alarm and leaves the others alone, so a keyed reminder is as safe to
+re-arm as an unkeyed one. The operation still decides which handler runs; the
+key only decides which alarm is which.
+
+A key must be non-empty, and the name it becomes must fit the 191-character
+column, which is checked on the composed name rather than the key alone so a
+long operation and a short key are caught too.
+
+The key is separated from the operation by a colon, so an operation may not hold
+one. Otherwise an unkeyed `deliver:item` and a `deliver` keyed `item` would be
+one name, and the second would silently take the first one's alarm. A key may
+hold colons of its own, because the operation before the first one cannot.
+
+## One alarm for a whole queue
+
+A key per item is not always what you want. An actor that only ever needs to
+know "what is next" can keep one alarm and let the handler drain everything now
+due before arming the next:
+
+```ruby
+def add(entry:)
+  self.entries = (entries + [ entry ]).sort_by { |item| item.fetch("wait_until") }
+  arm_next
+end
+
+def deliver
+  now = Time.current.to_i
+  due, pending = entries.partition { |item| item.fetch("wait_until") <= now }
+  due.each { |item| emit :send_push, **item.symbolize_keys }
+  self.entries = pending
+  arm_next
+end
+
+private
+
+def arm_next
+  earliest = entries.first
+  return unless earliest
+
+  schedule(at: Time.at(earliest.fetch("wait_until"))).deliver
+end
+```
+
+That costs one reminder row instead of one per item, and a coalesced occurrence
+cannot strand an entry because the handler drains by time rather than by alarm.
+Prefer it when the queue is large and the items are interchangeable; prefer
+`key:` when an item needs its own alarm that can be moved on its own.
+
+Solid Objects has no `unschedule`. A reminder stops when its handler does not
+re-arm it, and destroying an actor removes its reminders.
+
+Self-scheduling actors should also have a low-frequency application reconciler.
+It may read `SolidObjects::Instance.states_for`, `.without_pending_work`, and
+`.orphaned`, but every repair must go through `async`. Never bulk-update actor
+state around the lease and fencing checks.
+
+Suspended actors should be reported rather than silently resumed. Spread large
+repair batches with `available_at:` so reconciliation cannot stampede one
+mailbox or the worker fleet.

data/docs/research/solid_queue.md

@@ -472,7 +472,7 @@ The current `cardmagic/classifier` source uses RBS::Inline directly in Ruby file
 - [`.github/workflows/ruby.yml`](https://github.com/cardmagic/classifier/blob/48cdfa63f3efdba8149c8f47dd053ceebce5dfc1/.github/workflows/ruby.yml) generates signatures, validates them with RBS, and runs Steep.
 - [`Steepfile`](https://github.com/cardmagic/classifier/blob/48cdfa63f3efdba8149c8f47dd053ceebce5dfc1/Steepfile) enables strict diagnostics for the typed library while explicitly isolating incompatible extension files.
 
-Solid Objects will use the same source-adjacent convention. Every owned Ruby source file starts with `# rbs_inline: enabled`, declares its instance variables, and annotates public and private methods. Generated signatures are checked rather than hand-maintained as a competing source of truth.
+Solid Objects will use the same source-adjacent convention. Every owned Ruby source file starts with `# rbs_inline: enabled`, declares its instance variables, and annotates public and private methods. The build checks the generated signatures. Nobody maintains them by hand as a second authority.
 
 ## Related primary-source findings
 

data/docs/roadmap.md

@@ -134,7 +134,15 @@
   loads them in every process, and a rejected subscription reports which
   condition caused it instead of closing the socket silently.
 - Backpressure: mailbox/payload/state/result caps and fair yields exist;
-  distributed per-actor rate limits and global admission control do not.
+  distributed per-actor rate limits and global admission control do not. The
+  state cap is a limit rather than an operating point. `max_state_bytes`
+  defaults to 5 MB, and committed throughput measured on SQLite falls about 53
+  times between an empty state and 1 MB of state, which `docs/benchmarks.md`
+  records. A soft `warn_state_bytes` threshold, 64 KB by default, now
+  reports each commit above it as `solid_objects.state.large`. The hard default
+  stays at 5 MB, because lowering it would break an application whose actors
+  already exceed a lower value; a major release can lower it from the measured
+  curve.
 - Administration: `SolidObjects::Web` is a mountable Rack dashboard covering
   instances, mailbox, reminders, effects, broadcasts, dead letters, and
   processes, with actor-type and actor-id filtering, status filters, paging, a

data/lib/solid_objects/configuration.rb

@@ -15,6 +15,7 @@ module SolidObjects
     # @rbs @claim_scan_limit: Integer
     # @rbs @max_payload_bytes: Integer
     # @rbs @max_state_bytes: Integer
+    # @rbs @warn_state_bytes: Integer
     # @rbs @max_result_bytes: Integer
     # @rbs @max_attempts: Integer
     # @rbs @retry_delay: Proc
@@ -63,6 +64,7 @@ module SolidObjects
       :claim_scan_limit,
       :max_payload_bytes,
       :max_state_bytes,
+      :warn_state_bytes,
       :max_result_bytes,
       :max_attempts,
       :retry_delay,
@@ -116,6 +118,7 @@ module SolidObjects
       @claim_scan_limit = 100
       @max_payload_bytes = 1.megabyte
       @max_state_bytes = 5.megabytes
+      @warn_state_bytes = 64.kilobytes
       @max_result_bytes = 1.megabyte
       @max_attempts = 5
       @retry_delay = ->(attempt) { [ 2**(attempt - 1), 60 ].min.to_f }
@@ -223,6 +226,9 @@ module SolidObjects
       positive_values.each do |name, value|
         raise ArgumentError, "#{name} must be positive" unless value.positive?
       end
+      if warn_state_bytes > max_state_bytes
+        raise ArgumentError, "warn_state_bytes must not exceed max_state_bytes"
+      end
       message_retention_by_actor_type.each do |actor_type, retention|
         raise ArgumentError, "actor type cannot be empty" if actor_type.to_s.empty?
         raise ArgumentError, "message retention must be positive" unless retention.positive?
@@ -260,6 +266,7 @@ module SolidObjects
         claim_scan_limit:,
         max_payload_bytes:,
         max_state_bytes:,
+        warn_state_bytes:,
         max_result_bytes:,
         max_attempts:,
         process_heartbeat_interval:,

data/lib/solid_objects/executor.rb

@@ -25,9 +25,15 @@ module SolidObjects
 
       SolidObjects.instrument(:"message.started", **instrumentation_payload)
       result = invoke_actor(message_context)
-      ensure_query_did_not_mutate_state!(state_before)
       observable_changes = changed_observables(observables_before, actor.observable_values)
-      complete(result, observable_changes, state_changed: actor.state.to_h != state_before)
+      state_after = actor.state.to_h
+      ensure_query_did_not_mutate_state!(state_before, state_after)
+      complete(
+        result,
+        observable_changes,
+        state_after:,
+        state_changed: state_after != state_before
+      )
       true
     rescue LostActivation
       raise
@@ -59,11 +65,11 @@ module SolidObjects
       end
     end
 
-    # @rbs (Hash[String, untyped]) -> void
-    def ensure_query_did_not_mutate_state!(state_before)
+    # @rbs (Hash[String, untyped], Hash[String, untyped]) -> void
+    def ensure_query_did_not_mutate_state!(state_before, state_after)
       return unless message.delivery_mode == "sync"
       return unless actor.class.definition.queries.key?(message.operation.to_sym)
-      return if actor.state.to_h == state_before
+      return if state_after == state_before
 
       raise InvalidActor, "query #{message.operation.inspect} mutated actor state"
     end
@@ -75,10 +81,10 @@ module SolidObjects
       end
     end
 
-    # @rbs (untyped, Hash[String, untyped], state_changed: bool) -> void
-    def complete(result, observable_changes, state_changed:)
-      serialized_state = Serialization.dump(
-        actor.state.to_h,
+    # @rbs (untyped, Hash[String, untyped], state_after: Hash[String, untyped], state_changed: bool) -> void
+    def complete(result, observable_changes, state_after:, state_changed:)
+      dumped_state = Serialization.dump_with_byte_size(
+        state_after,
         max_bytes: SolidObjects.configuration.max_state_bytes
       )
       serialized_result = Serialization.dump(
@@ -102,7 +108,7 @@ module SolidObjects
         locked_message = Message.lock.find(message.id)
         execute_commit_actions(commit_action_intents)
         instance.update!(
-          state: serialized_state,
+          state: dumped_state.value,
           state_version: actor.class.state_version,
           state_revision: locked_message.sequence,
           last_used_at: SolidObjects.database_adapter.database_now
@@ -129,17 +135,17 @@ module SolidObjects
       end
 
       observable_changes.each_key do |observable_name|
-        SolidObjects.instrument(
+        SolidObjects.instrument_after_commit(
           :"broadcast.enqueued",
           **instrumentation_payload,
           observable_name:
         )
       end
       moved_reminders.each do |moved|
-        SolidObjects.instrument(:"reminder.replaced", **moved)
+        SolidObjects.instrument_after_commit(:"reminder.replaced", **moved)
       end
       enqueued_effects.each do |effect|
-        SolidObjects.instrument(
+        SolidObjects.instrument_after_commit(
           :"effect.enqueued",
           effect_id: effect.effect_id,
           effect_name: effect.name,
@@ -148,10 +154,25 @@ module SolidObjects
           actor_id: message.actor_id
         )
       end
-      SolidObjects.instrument(:"message.completed", **instrumentation_payload)
+      report_large_state(dumped_state.byte_size)
+      SolidObjects.instrument_after_commit(:"message.completed", **instrumentation_payload)
       SolidObjects.wake_up.signal
     end
 
+    # @rbs (Integer) -> void
+    def report_large_state(byte_count)
+      threshold = SolidObjects.configuration.warn_state_bytes
+      return if byte_count <= threshold
+
+      SolidObjects.instrument_after_commit(
+        :"state.large",
+        actor_type: message.actor_type,
+        actor_id: message.actor_id,
+        byte_count:,
+        threshold_bytes: threshold
+      )
+    end
+
     # @rbs (Array[Actor::CommitActionIntent]) -> void
     def execute_commit_actions(intents)
       ensure_application_database_is_shared! if intents.any?
@@ -352,7 +373,7 @@ module SolidObjects
         end
       end
 
-      SolidObjects.instrument(
+      SolidObjects.instrument_after_commit(
         :"message.failed",
         **instrumentation_payload,
         error_class: error.class.name,
@@ -387,7 +408,7 @@ module SolidObjects
         claimed_message.destroy!
       end
 
-      SolidObjects.instrument(
+      SolidObjects.instrument_after_commit(
         :"message.rejected",
         **instrumentation_payload,
         code: rejection.code

data/lib/solid_objects/instrumentation.rb

@@ -6,5 +6,38 @@ module SolidObjects
     def instrument(event, **payload, &block)
       ActiveSupport::Notifications.instrument("solid_objects.#{event}", payload, &block)
     end
+
+    # @rbs (Symbol, **untyped) -> void
+    def instrument_after_commit(event, **payload)
+      instrument(event, **payload)
+    rescue => error
+      report_instrumentation_failure(event, error)
+    end
+
+    private
+
+    # @rbs (Symbol, Exception) -> void
+    def report_instrumentation_failure(event, error)
+      instrument(
+        :"instrumentation.failed",
+        instrumentation_event: "solid_objects.#{event}",
+        error_class: error.class.name
+      )
+    rescue => failure
+      log_instrumentation_failure(event, failure)
+    end
+
+    # @rbs (Symbol, Exception) -> void
+    def log_instrumentation_failure(event, error)
+      SolidObjects.configuration.logger.error(
+        {
+          event: "solid_objects.instrumentation.failed",
+          instrumentation_event: "solid_objects.#{event}",
+          error_class: error.class.name
+        }
+      )
+    rescue
+      nil
+    end
   end
 end

data/lib/solid_objects/serialization.rb

@@ -4,17 +4,26 @@ module SolidObjects
   module Serialization
     MAX_NESTING = 100
 
+    Dumped = Data.define(:value, :byte_size)
+
     class << self
       # @rbs (untyped, ?max_bytes: Integer?) -> untyped
       def dump(value, max_bytes: nil)
+        return normalize(value) unless max_bytes
+
+        dump_with_byte_size(value, max_bytes:).value
+      end
+
+      # @rbs (untyped, ?max_bytes: Integer?) -> Dumped
+      def dump_with_byte_size(value, max_bytes: nil)
         normalized = normalize(value)
-        encoded = JSON.generate(normalized, max_nesting: MAX_NESTING)
+        byte_size = JSON.generate(normalized, max_nesting: MAX_NESTING).bytesize
 
-        if max_bytes && encoded.bytesize > max_bytes
+        if max_bytes && byte_size > max_bytes
           raise PayloadTooLarge, "serialized value exceeds #{max_bytes} bytes"
         end
 
-        normalized
+        Dumped.new(value: normalized, byte_size:)
       rescue JSON::GeneratorError, EncodingError => error
         raise InvalidPayload, error.message
       end
@@ -60,7 +69,11 @@ module SolidObjects
         raise InvalidPayload, "serialized value is nested too deeply" if depth > MAX_NESTING
 
         case value
-        when nil, true, false, String, Integer
+        when nil, true, false, Integer
+          value
+        when String
+          raise InvalidPayload, "strings must hold valid #{value.encoding} bytes" unless value.valid_encoding?
+
           value
         when Float
           raise InvalidPayload, "non-finite numbers are not supported" unless value.finite?
@@ -89,7 +102,7 @@ module SolidObjects
 
       # @rbs (untyped) -> String
       def normalize_key(key)
-        return key if key.is_a?(String)
+        return normalize(key) if key.is_a?(String)
         return key.to_s if key.is_a?(Symbol)
 
         raise InvalidPayload, "JSON object keys must be strings or symbols"

data/lib/solid_objects/version.rb

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

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

@@ -2,7 +2,7 @@
 
 module SolidObjects
   class Configuration
-    @table_name_prefix: String
+    @process_alive_threshold: Float
 
     @shutdown_timeout: Float
 
@@ -60,6 +60,8 @@ module SolidObjects
 
     @transmission_actor_type_resolver: Proc
 
+    @table_name_prefix: String
+
     @polling_interval: Float
 
     @idle_polling_interval: Float
@@ -84,6 +86,8 @@ module SolidObjects
 
     @max_state_bytes: Integer
 
+    @warn_state_bytes: Integer
+
     @max_result_bytes: Integer
 
     @max_attempts: Integer
@@ -94,8 +98,6 @@ module SolidObjects
 
     @process_heartbeat_interval: Float
 
-    @process_alive_threshold: Float
-
     attr_accessor table_name_prefix: untyped
 
     attr_accessor polling_interval: untyped
@@ -122,6 +124,8 @@ module SolidObjects
 
     attr_accessor max_state_bytes: untyped
 
+    attr_accessor warn_state_bytes: untyped
+
     attr_accessor max_result_bytes: untyped
 
     attr_accessor max_attempts: untyped

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

@@ -24,14 +24,17 @@ module SolidObjects
     # @rbs (MessageContext) -> untyped
     def invoke_actor: (MessageContext) -> untyped
 
-    # @rbs (Hash[String, untyped]) -> void
-    def ensure_query_did_not_mutate_state!: (Hash[String, untyped]) -> void
+    # @rbs (Hash[String, untyped], Hash[String, untyped]) -> void
+    def ensure_query_did_not_mutate_state!: (Hash[String, untyped], Hash[String, untyped]) -> void
 
     # @rbs (Hash[String, untyped], Hash[String, untyped]) -> Hash[String, untyped]
     def changed_observables: (Hash[String, untyped], Hash[String, untyped]) -> Hash[String, untyped]
 
-    # @rbs (untyped, Hash[String, untyped], state_changed: bool) -> void
-    def complete: (untyped, Hash[String, untyped], state_changed: bool) -> void
+    # @rbs (untyped, Hash[String, untyped], state_after: Hash[String, untyped], state_changed: bool) -> void
+    def complete: (untyped, Hash[String, untyped], state_after: Hash[String, untyped], state_changed: bool) -> void
+
+    # @rbs (Integer) -> void
+    def report_large_state: (Integer) -> void
 
     # @rbs (Array[Actor::CommitActionIntent]) -> void
     def execute_commit_actions: (Array[Actor::CommitActionIntent]) -> void

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

@@ -4,5 +4,16 @@ module SolidObjects
   module Instrumentation
     # @rbs (Symbol, **untyped) { (Hash[Symbol, untyped]) -> untyped } -> untyped
     def instrument: (Symbol, **untyped) { (Hash[Symbol, untyped]) -> untyped } -> untyped
+
+    # @rbs (Symbol, **untyped) -> void
+    def instrument_after_commit: (Symbol, **untyped) -> void
+
+    private
+
+    # @rbs (Symbol, Exception) -> void
+    def report_instrumentation_failure: (Symbol, Exception) -> void
+
+    # @rbs (Symbol, Exception) -> void
+    def log_instrumentation_failure: (Symbol, Exception) -> void
   end
 end

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

@@ -4,9 +4,25 @@ module SolidObjects
   module Serialization
     MAX_NESTING: ::Integer
 
+    class Dumped < Data
+      attr_reader value(): untyped
+
+      attr_reader byte_size(): untyped
+
+      def self.new: (untyped value, untyped byte_size) -> instance
+                  | (value: untyped, byte_size: untyped) -> instance
+
+      def self.members: () -> [ :value, :byte_size ]
+
+      def members: () -> [ :value, :byte_size ]
+    end
+
     # @rbs (untyped, ?max_bytes: Integer?) -> untyped
     def self.dump: (untyped, ?max_bytes: Integer?) -> untyped
 
+    # @rbs (untyped, ?max_bytes: Integer?) -> Dumped
+    def self.dump_with_byte_size: (untyped, ?max_bytes: Integer?) -> Dumped
+
     # @rbs (untyped) -> untyped
     def self.load: (untyped) -> untyped
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.14.1
+  version: 0.14.3
 platform: ruby
 authors:
 - Lucas Carlson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-24 00:00:00.000000000 Z
+date: 2026-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable
@@ -323,6 +323,7 @@ files:
 - benchmark/idle_polling.rb
 - benchmark/processing.rb
 - benchmark/query_count.rb
+- benchmark/state_size.rb
 - benchmark/support.rb
 - benchmark/sync_latency.rb
 - config/routes.rb
@@ -355,6 +356,7 @@ files:
 - docs/migrating-existing-state.md
 - docs/operations.md
 - docs/realtime.md
+- docs/reminders.md
 - docs/research/solid_queue.md
 - docs/roadmap.md
 - docs/security.md