solid_objects 0.14.2 → 0.14.3

data/benchmark/state_size.rb

@@ -0,0 +1,5 @@
+# rbs_inline: enabled
+
+require_relative "support"
+
+SolidObjectsBenchmark.state_size

data/benchmark/support.rb

@@ -7,6 +7,25 @@ require "solid_objects"
 
 module SolidObjectsBenchmark
   DATABASE_PATH = File.expand_path("../tmp/solid_objects_benchmark.sqlite3", __dir__)
+  STATE_SIZES = [ 0, 16 * 1_024, 128 * 1_024, 1_024 * 1_024 ].freeze
+  STATE_ENTRY_BYTES = 26
+
+  class StateSizeActor < SolidObjects::Actor
+    actor_type "benchmark-state-size"
+
+    attribute :count, default: 0
+    attribute :filler, default: -> { {} }
+
+    def fill(size:)
+      entries = size / STATE_ENTRY_BYTES
+      self.filler = Array.new(entries) { |index| [ "key-#{index}", "value-#{index}" ] }.to_h
+      filler.length
+    end
+
+    def increment
+      self.count = count + 1
+    end
+  end
 
   class CounterActor < SolidObjects::Actor
     actor_type "benchmark-counter"
@@ -289,6 +308,12 @@ module SolidObjectsBenchmark
       )
     end
 
+    # @rbs () -> void
+    def state_size
+      warm_up_state_size
+      STATE_SIZES.each { |size| measure_state_size(size) }
+    end
+
     # @rbs () -> void
     def query_count
       turn = message_turn_query_count
@@ -433,6 +458,44 @@ module SolidObjectsBenchmark
       count.times { |index| references[index % actor_count].async.increment }
     end
 
+    # @rbs () -> void
+    def warm_up_state_size
+      reference = StateSizeActor.ref("state-size-warm-up")
+      reference.fill(size: 0)
+      count.times { reference.async.increment }
+      worker = SolidObjects::Worker.new
+      drain(worker)
+    ensure
+      worker&.stop
+    end
+
+    # @rbs (Integer) -> void
+    def measure_state_size(size)
+      silence_large_state_warning
+      actor_id = "state-size-#{size}"
+      reference = StateSizeActor.ref(actor_id)
+      reference.fill(size:)
+      state_bytes = committed_state_bytes(actor_id)
+      count.times { reference.async.increment }
+      worker = SolidObjects::Worker.new
+      measure("process #{count} messages with #{state_bytes} bytes of state") { drain(worker) }
+    ensure
+      worker&.stop
+    end
+
+    # @rbs () -> void
+    def silence_large_state_warning
+      return unless SolidObjects.configuration.respond_to?(:warn_state_bytes=)
+
+      SolidObjects.configuration.warn_state_bytes = SolidObjects.configuration.max_state_bytes
+    end
+
+    # @rbs (String) -> Integer
+    def committed_state_bytes(actor_id)
+      instance = SolidObjects::Instance.find_by!(actor_type: "benchmark-state-size", actor_id:)
+      JSON.generate(instance.state).bytesize
+    end
+
     # @rbs (SolidObjects::Worker) -> Integer
     def drain(worker)
       processed = 0

data/docs/adr/0006-at-least-once-delivery.md

@@ -13,7 +13,7 @@ Mailbox delivery is at least once. State mutation, message completion, result pe
 
 Actor code receives message ID, request ID, attempt, enqueue time, and idempotency key. Documentation requires idempotency for effects outside the actor commit.
 
-Message handlers themselves can run more than once. Sequential execution means one valid activation runs one turn at a time; it does not mean a handler runs once. Handlers for transitions such as `launch`, `checkout`, or `submit` must inspect durable actor state and return safely when the transition already happened. External calls belong in an outbox and still require downstream idempotency.
+Message handlers themselves can run more than once. Sequential execution means that one valid activation runs one turn at a time. It does not guarantee that a handler runs only once. Handlers for transitions such as `launch`, `checkout`, or `submit` must inspect durable actor state and return safely when the transition already happened. External calls belong in an outbox and still require downstream idempotency.
 
 ## Consequences
 

data/docs/architecture.md

@@ -7,8 +7,9 @@ It is a database-backed virtual actor runtime for MySQL, PostgreSQL, and
 SQLite. A virtual actor is a logical object addressed by type and ID whose
 in-memory activation is created on demand, processes one mailbox turn at a
 time, persists JSON state, and can disappear when idle without losing its
-identity or state. This ports the programming model, not Cloudflare's
-serverless runtime, global placement, storage API, or platform guarantees.
+identity or state. This gem ports the programming model. It does not port
+Cloudflare's serverless runtime, global placement, storage API, or platform
+guarantees.
 
 The runtime contract is:
 
@@ -128,8 +129,8 @@ instance first prevents a claimed reminder from recreating a destroyed actor.
 The broadcast worker claims committed observable-change rows, renders
 idempotent scalar Turbo replacements with component invalidation metadata,
 broadcasts to a signed actor stream, and records delivery. It never renders
-personalized component HTML. Current actor state remains the reconnect and
-request-time component source of truth.
+personalized component HTML. On reconnect, and on a request-time component
+render, Solid Objects reads the current actor state.
 
 ### Process registry
 
@@ -482,7 +483,7 @@ A reminder record contains actor identity, a reminder name, target message, JSON
 schedule(at: 30.minutes.from_now).expire
 ```
 
-Reminders are keyed by `(actor, reminder name)`, enforced by a unique index on `(instance_id, name)`. `schedule` is therefore an upsert: scheduling a name that is already armed moves that alarm instead of adding another, which is what makes re-arming safe from a handler that may run more than once. An actor needing several pending items should arm one alarm for the earliest and drain everything due when it fires, rather than one alarm per item; the [reminders guide](reminders.md#one-alarm-for-a-whole-queue) shows that pattern. A move that changes `next_run_at` emits `solid_objects.reminder.replaced`, because the replacement is otherwise indistinguishable from a first schedule.
+Reminders are keyed by `(actor, reminder name)`, enforced by a unique index on `(instance_id, name)`. `schedule` is therefore an upsert: scheduling a name that is already armed moves that alarm instead of adding another, so re-arming is safe from a handler that may run more than once. An actor needing several pending items should arm one alarm for the earliest and drain everything due when it fires, rather than one alarm per item; the [reminders guide](reminders.md#one-alarm-for-a-whole-queue) shows that pattern. A move that changes `next_run_at` emits `solid_objects.reminder.replaced`, because the replacement is otherwise indistinguishable from a first schedule.
 
 When due, the scheduler locks the source instance and creates a normal mailbox
 row with an idempotency key derived from reminder ID and occurrence. The
@@ -698,7 +699,7 @@ Backoff and a retry limit prevent tight loops. The poison message blocks its act
 
 ### Handler redelivery
 
-Sequential processing does not mean single execution. A handler can run, lose its lease before commit, and run again. Logical transitions must guard on durable state:
+Ordered processing does not prevent repeated execution. A handler can run, lose its lease before commit, and run again. Logical transitions must guard on durable state:
 
 ```ruby
 def launch

data/docs/authorization.md

@@ -1,9 +1,9 @@
 # Authorization policies
 
-Solid Objects treats actor identities as identifiers, never capabilities.
-Knowing an actor ID, message ID, or signed stream token grants no permission.
-All five policies deny by default, so a generated installation is
-intentionally inert until the host application defines its trust boundary.
+Solid Objects treats actor identities as identifiers. They are not
+capabilities. An actor ID, a message ID, or a signed stream token grants no
+permission. All five policies deny by default, so a generated installation
+answers nothing until the host application defines its trust boundary.
 
 ## Policy reference
 

data/docs/benchmarks.md

@@ -1,8 +1,8 @@
 # Performance and storage costs
 
-These numbers are development measurements, not universal capacity guarantees.
-They include the runtime's Active Record and database query overhead and will
-vary with hardware, schema size, connection pools, durability settings, and
+These numbers are development measurements. They do not guarantee capacity.
+They include the runtime's Active Record and database query overhead, and they
+change with hardware, schema size, connection pools, durability settings, and
 contention.
 
 ## Idle SQLite polling
@@ -109,6 +109,51 @@ result is why Solid Objects does not publish one latency promise. Network
 topology, adapter behavior, host schema, logging, callbacks, and contention all
 matter.
 
+## State size and committed throughput
+
+A turn commits the whole state image. It copies the state, encodes it, and
+writes the row, so every message pays for the size of the state its actor
+keeps. Run the scenario with:
+
+```bash
+COUNT=300 bundle exec ruby -Ilib benchmark/state_size.rb
+```
+
+Measured 2026-08-29 on an Apple M5 with 24 GB RAM, Ruby 4.0.5, Rails 8.1.3.1,
+and SQLite 3.53.2. One hot actor received 300 messages at each state size. Each
+figure is the median of five runs, and the two trees ran one after the other in
+each round. The state holds many small entries, because a copy visits every
+node, and one long string of the same length costs much less. The harness sets
+`warn_state_bytes` to the hard limit, so neither tree pays for an event that
+only one of them can emit.
+
+| Committed state | Before | After | Change |
+| ---: | ---: | ---: | ---: |
+| 23 bytes | 1,268.0 messages/s | 1,252.5 messages/s | -1.2% |
+| 13,662 bytes | 624.1 messages/s | 654.1 messages/s | +4.8% |
+| 118,786 bytes | 169.3 messages/s | 174.6 messages/s | +3.1% |
+| 1,026,356 bytes | 21.6 messages/s | 23.8 messages/s | +10.2% |
+
+The "before" tree copied the whole state three times per committed turn and
+encoded a string that it discarded whenever the caller gave no byte limit. The
+"after" tree copies it twice and encodes only where a limit applies. It also
+checks the encoding of every string it normalizes, which the discarded encoding
+used to do, so part of the saving pays for that check. The gain grows with the
+state, because the database write dominates a small turn. The empty-state row
+sits inside run-to-run variance.
+
+The curve matters more than the change. Throughput falls about 28 times between
+13 KB and 1 MB of state, and about 53 times between an empty state and 1 MB.
+The `max_state_bytes` default of 5 MB is therefore a limit rather than an
+operating point. `warn_state_bytes` defaults to 64 KB, and each commit above it
+reports `solid_objects.state.large`. The Node package carries the same setting
+as `warnStateBytes` and defaults it to 128 KB, because its measured curve falls
+later: it keeps 98% of its empty-state throughput at 16 KB, where this gem
+keeps 52% at 13 KB.
+
+These are developer-laptop numbers on one adapter. They show shape and ratio,
+not a capacity guarantee.
+
 ## Reactive delivery paths
 
 Measured 2026-08-09 on an Apple M5 with 200 iterations, for one actor mutation

data/docs/correctness.md

@@ -78,8 +78,8 @@ Destruction is synchronous, forbidden from actor context, authorized by
 
 ## Handler idempotency
 
-Sequential does not mean once. A message such as `launch` still needs a durable
-guard:
+Ordered execution does not prevent repeated execution. A message such as
+`launch` still needs a durable guard:
 
 ```ruby
 def launch

data/docs/fit.md

@@ -24,7 +24,13 @@ Solid Objects is a good candidate when most of these are true:
   asynchronous features, a Solid Objects runtime process.
 
 Typical fits include checkout state machines, collaborative rooms, device
-twins, durable assessments, approval workflows, and user-specific scheduling.
+twins, durable assessments, approval workflows, user-specific scheduling, and
+low-rate quotas that a reminder refills.
+
+A workflow fits when one entity owns the mutable state and its mailbox holds
+the step order. A durable execution engine that replays named steps from a step
+log is a different tool: Solid Objects redelivers an ordered message and
+retries it, and does not replay a handler from a step log.
 
 ## Poor fit and anti-patterns
 
@@ -46,10 +52,21 @@ when any of these dominate:
 - State that is clearer as a normal record with database constraints and direct
   service methods.
 
-A rate limiter is usually a poor actor: it is hot, request-critical, and often
-expires rather than requiring permanent message history. An impressions
-pipeline is also a poor actor: its value is high-throughput append and
-aggregation, not serialized mutable state.
+A request-path rate limiter is usually a poor actor: it is hot,
+request-critical, and often expires rather than requiring permanent message
+history. A low-rate quota is the case that does fit, such as five password
+resets an hour for one account, where a reminder refills the bucket and each
+check is one durable ordered message. An impressions pipeline is also a poor
+actor, because its value comes from high-throughput append and aggregation. It
+does not need serialized mutable state.
+
+[Solid Objects Pro](https://solidobjects.pro/) is the commercial scaling layer
+for the high-QPS cases in this section. Grouped operations coalesce concurrent
+calls into one bulk insert. Ephemeral operations hold a loss-tolerant call in
+process memory and write no journal row, which is the mode for an abuse limiter,
+a presence signal, or a view count. Reactive projections materialize a read
+model from the durable broadcast outbox, so request-path reads stop competing
+with mailbox work.
 
 ## Cost model
 
@@ -94,5 +111,5 @@ Before adopting an actor, answer:
 10. How will existing state be cut over and rolled back?
 
 Benchmark the actual host database and deployment topology before committing a
-latency-sensitive surface. Local benchmark results are evidence about query
-shape, not universal capacity guarantees.
+latency-sensitive surface. Local benchmark results show query shape. They do
+not guarantee capacity.

data/docs/local-testing.md

@@ -24,9 +24,9 @@ SOLID_OBJECTS_DATABASE_URL=postgresql://solid_objects:solid_objects@127.0.0.1:54
   bundle exec rake test
 ```
 
-Running this locally is worth the setup: it is what caught the PostgreSQL
-version comparison reading a packed integer, where `170010` compared greater
-than any minimum and made the check useless on the adapter it mattered most for.
+The setup is worth the effort. This local suite caught a PostgreSQL version
+comparison that read a packed integer, where `170010` compared greater than any
+minimum and made the check useless on the adapter that needed it most.
 
 ## MySQL and Redis in Docker
 

data/docs/migrating-existing-state.md

@@ -2,7 +2,7 @@
 
 Moving an existing Redis, cache, or key-value state machine into Solid Objects
 is a data migration and a coordination cutover. Treat it as a staged production
-change, not a rewrite that switches storage in one deploy.
+change. Do not switch the storage in one deploy.
 
 ## 1. Write down the existing contract
 

data/docs/operations.md

@@ -143,9 +143,9 @@ loader participates in Rails preparation callbacks so a development reload can
 replace a registered actor class without loading unrelated application code.
 
 An actor registers itself as its class loads, and a web process resolves
-actors by name for Cable subscriptions and component renders. Loading them in
-every process is what lets a freshly booted web process serve a live card for
-an actor no request in that process has rendered yet.
+actors by name for Cable subscriptions and component renders. Solid Objects
+loads the actors in every process, so a freshly booted web process can serve a
+live card for an actor that no request in that process has rendered yet.
 
 Worker and outbox counts can be overridden on the command line:
 
@@ -200,6 +200,7 @@ end
 | `max_messages_per_activation_pass` | 50 |
 | `max_activation_duration` | 5 seconds |
 | `max_mailbox_length` | 10,000 |
+| `warn_state_bytes` | 64 KB |
 | `max_attempts` | 5 |
 | `process_heartbeat_interval` | 15 seconds |
 | `process_alive_threshold` | 60 seconds |
@@ -217,6 +218,15 @@ Payload, state, and result byte limits; retry delay; table prefix; logging;
 wake-up; broadcast; database; and authorization adapters are also configurable.
 Invalid lease intervals, component counts, and size limits fail fast at boot.
 
+`max_state_bytes` defaults to 5 MB, which is a limit rather than an operating
+point. A turn copies the whole state, encodes it, and writes the row, so
+committed throughput falls long before that limit: measured on SQLite, about 28
+times between 13 KB and 1 MB of state. See `docs/benchmarks.md` for the curve.
+`warn_state_bytes` is the soft threshold, and it must not exceed
+`max_state_bytes`. Each commit above it reports `solid_objects.state.large` and
+nothing else changes, so an application that already keeps a large state keeps
+working while its operator learns the cost.
+
 Keep lease duration comfortably above renewal interval and expected database
 pause time. A handler can exceed the pass-duration budget because Ruby code is
 not safely preempted; alert on message duration and isolate untrusted work.
@@ -278,7 +288,7 @@ Use:
 
 Spread large repairs with `available_at:`. Report at least bootstrapped,
 reconfigured, revived, suspended, and orphaned counts. A nonzero revived count
-is evidence that alarms are being lost.
+shows that alarms are lost.
 
 Never bulk-update actor state. That bypasses lease ownership and fencing.
 
@@ -308,6 +318,7 @@ Alert on:
 - ready and claimed membership counts;
 - mailbox-full rejections;
 - actor turn duration and failures;
+- committed state above `warn_state_bytes`;
 - lost-activation rate;
 - dead-letter creation;
 - actor destruction rate;
@@ -344,6 +355,23 @@ per queued item keeps only the last, and the earlier wake-up never happens.
 Watch this event if your actors schedule from a loop or from a handler that can
 run more than once. Rescheduling to the same time reports nothing.
 
+`solid_objects.state.large` reports a committed turn whose state exceeded
+`warn_state_bytes`. The payload carries the actor identity, the `byte_count`
+the commit wrote, and the `threshold_bytes` it passed. It never carries the
+state. The event reports after the commit, so a turn that rolled back reports
+nothing. Every commit above the threshold reports, including a synchronous
+query and a turn that changed nothing, so a hot actor reports once per message.
+Aggregate by actor rather than alert on each event, and watch the reported size
+rather than the event rate: a state that grows without a bound is what this
+event exists to find. `solid-objects-js` emits the same event under the same
+name and payload.
+
+`solid_objects.instrumentation.failed` reports a subscriber that raised while
+the runtime reported a committed turn. The payload carries the
+`instrumentation_event` that failed and the `error_class`. The turn itself is
+unaffected, because it already committed. Watch this event to find a broken
+subscriber, which would otherwise be silent.
+
 `solid_objects.component.refreshed` covers every authorized component refresh
 request. Its payload carries the actor identity, `component_name`,
 `component_key`, declared `dependencies`, `refresh_method`, the rendered

data/docs/realtime.md

@@ -421,8 +421,8 @@ configuration.component_authorization_context = ->(controller:) { controller.cur
 configuration.payload_authorization_context = ->(connection:) { connection.current_account }
 ```
 
-The resolved value is what the payload block receives as its second argument and
-what `authorize_query` receives as `authorization_context`. A resolver may also
+The payload block receives the resolved value as its second argument, and
+`authorize_query` receives it as `authorization_context`. A resolver may also
 accept `payload_name:` when the subject depends on which payload was requested.
 The default returns the connection unchanged, so an application that has not
 configured one is unaffected.

data/docs/reminders.md

@@ -22,9 +22,9 @@ 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, and it
-is what 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:
+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.
@@ -51,9 +51,9 @@ end
 ```
 
 Two entries now leave two reminders. Scheduling the same key again moves that
-item's alarm and leaves the others alone, which is what makes a keyed reminder
-as safe to re-arm as an unkeyed one. The operation still decides which handler
-runs; the key only decides which alarm is which.
+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

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