perf: cut one state copy per committed turn

[cardmagic]

Closes #57.

What changed

1. Executor#call built three full copies of the actor state per committed
   turn. It now builds two. One after image answers whether the state changed,
   whether a synchronous query mutated state, and what the committed row holds.
2. Serialization.dump encoded every value to measure it, then discarded the
   string whenever the caller passed no max_bytes, which most call sites do.
   It now encodes only when a limit applies. dump_with_byte_size returns the
   encoded size beside the normalized value, so the commit that reports the
   size pays for one encoding.
3. state_size_warning_bytes is a new soft threshold, 64 KB by default. A
   commit above it reports solid_objects.state.large with the actor identity,
   the byte count, and the threshold. The event carries no application state and
   reports after the commit, so a rolled back turn reports nothing.
   max_state_bytes keeps its 5 MB default.
4. benchmark/state_size.rb reports committed throughput at each state size.

Version 0.14.3.

Effects to review

• API: Serialization.dump_with_byte_size is new. Serialization.dump
  keeps its signature and its return value.
• Correctness: the query mutation guard now compares the image taken after
  the observables are read. A query whose observable block mutates state now
  fails with InvalidActor; before, that mutation was committed silently.
• Correctness: dump without a max_bytes no longer rejects a value that
  JSON cannot encode, such as a string holding invalid UTF-8. Every call site
  that applies a limit, including the committed state and result, still rejects
  it.
• Migration: none. No schema change, no configuration change is required.
• Security: none. The new event names the actor and the size only.

Measured

Apple M5, 24 GB RAM, Ruby 4.0.5, Rails 8.1.3.1, SQLite 3.53.2. One hot actor,
300 messages per size, median of five runs, with the two trees run one after
the other in each round.

Committed state	Before	After	Change
23 bytes	1,171.4 messages/s	1,204.0 messages/s	+2.8%
13,662 bytes	642.8 messages/s	644.9 messages/s	+0.3%
118,786 bytes	165.5 messages/s	181.2 messages/s	+9.5%
1,026,356 bytes	20.6 messages/s	24.5 messages/s	+18.9%

The curve matters more than the change: throughput falls about 49 times between
an empty state and 1 MB of state. That is the evidence behind the soft
threshold and behind the roadmap correction, which now records that
max_state_bytes describes a limit rather than an operating point.

Observed failures before the fix

Every test was written first and watched fail.

StateCommitTest#test_a_committed_message_builds_one_state_image_after_its_handler_runs
Expected: 1
  Actual: 2

StateCommitTest#test_a_committed_query_builds_one_state_image_after_its_handler_runs
Expected: 1
  Actual: 3

SerializationTest#test_does_not_encode_a_value_that_has_no_byte_limit
SolidObjects::InvalidPayload: source sequence is illegal/malformed utf-8

SerializationTest#test_reports_the_encoded_byte_size_beside_the_normalized_value
NoMethodError: undefined method 'dump_with_byte_size' for module SolidObjects::Serialization

ConfigurationTest#test_warns_about_large_state_well_below_the_hard_state_limit
NoMethodError: undefined method 'state_size_warning_bytes' for an instance of SolidObjects::Configuration

StateCommitTest#test_reports_committed_state_above_the_soft_threshold
NoMethodError: undefined method 'state_size_warning_bytes=' for an instance of SolidObjects::Configuration

One test is regression cover rather than a red-to-green step. The issue said
existing tests covered the query mutation guard; none did.
StateCommitTest#test_a_query_that_mutates_state_fails_its_message now holds
that behavior, and it passed against the tree before the change.

Validation

bundle exec rake            # 593 runs, 1926 assertions, 0 failures, 0 errors, 15 skips
                            # standard, rubocop, rbs validate, steep, brakeman all clean
COUNT=300 bundle exec ruby -Ilib benchmark/state_size.rb

The 15 skips are the PostgreSQL, MySQL, and Redis tests that a SQLite run
excludes. The count is unchanged by this branch.

Parity

The JavaScript port carries a larger version of the same problem and the same
5 MB default, tracked at cardmagic/solid-objects-js#32. That port is not in this
pull request.

[cardmagic]

@greptileai review

[greptile-apps]

Greptile Summary

The PR reduces state copying and unnecessary serialization work during committed actor turns while adding a configurable large-state warning. It also isolates post-commit notifications so subscriber and logger failures do not disrupt completed turns.

• Reuses one post-handler state image for mutation checks and persistence.
• Adds byte-size-aware serialization and validates string encodings during normalization.
• Reports committed states above the configurable warning threshold.
• Contains post-commit instrumentation failures and preserves subsequent completion reporting.
• Adds state-size benchmarks, operational documentation, signatures, and regression coverage.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; both previously reported post-commit notification paths are contained at the current head.

Important Files Changed

Filename	Overview
lib/solid_objects/executor.rb	Reuses the post-handler state image, persists its measured serialization, emits the large-state event, and routes post-commit notifications through the isolation wrapper.
lib/solid_objects/instrumentation.rb	Adds layered containment for subscriber, failure-reporter, and logger errors, resolving both previously reported post-commit notification failures.
lib/solid_objects/serialization.rb	Avoids JSON generation when no byte limit applies while preserving payload validation and exposing encoded byte size when required.
lib/solid_objects/configuration.rb	Adds a positive soft state-size threshold constrained not to exceed the existing hard limit.
test/integration/state_commit_test.rb	Covers state-copy counts, query mutation detection, warning emission, rollback silence, and nested instrumentation failure isolation.

Sequence Diagram

sequenceDiagram
  participant W as Worker
  participant E as Executor
  participant A as Actor
  participant DB as Database
  participant I as Instrumentation
  W->>E: Process message
  E->>A: Invoke handler
  E->>A: Read observables and state_after
  E->>E: Check query mutation
  E->>E: Normalize and measure state
  E->>DB: Commit state and message
  DB-->>E: Commit succeeds
  E->>I: Report post-commit events
  alt Subscriber raises
    I->>I: Report instrumentation.failed
    I-->>E: Contain reporting failure
  end
  E->>W: Signal wake-up

Loading

_{Reviews (3): Last reviewed commit: "fix: close the last hole in post-commit ..." | Re-trigger Greptile}

[cardmagic]

@greptileai review

[cardmagic]

@greptileai review