fix: bound the remembered keys by size

An idempotency key has no length limit on every adapter. SQLite ignores
the `limit: 191` the schema declares, so a 1000-character key is stored
whole:

    sent 1000 chars, stored 1000 chars
    remembered entry length: 1000

Before this branch such a key sat in one message row that retention
removed. The remembered list holds 64 of them on the instance row, which
survives as long as the actor, so the growth became unbounded and
persistent.

`retained_idempotency_keys_bytes` bounds the serialized list at 16 KB.
An actor drops its oldest keys until the list fits, so a key long enough
to fill the limit by itself is never remembered and its lookup answers
`nil` rather than raising.

Validation: bundle exec rake (787 runs, 0 failures).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: cardmagic

CHANGELOG.md

@@ -28,6 +28,10 @@
   `retained_idempotency_keys` bounds the memory and defaults to 64 keys for
   each actor. A lookup by request id cannot make the distinction, because the
   runtime, not the caller, generates a request id and no actor remembers one.
+  `retained_idempotency_keys_bytes` bounds the serialized memory as well,
+  because an idempotency key has no length limit on every adapter and the memory
+  outlives the message row. An actor drops its oldest keys until the list fits,
+  so a key long enough to fill the limit by itself is never remembered.
 - Add `db/migrate/20260923000000_add_solid_objects_completed_idempotency_keys.rb`,
   which adds `instances.completed_idempotency_keys` as `jsonb` on PostgreSQL and
   `json` elsewhere. An application installs it with

docs/architecture.md

@@ -446,7 +446,9 @@ a lost result from a request that never arrived. The memory is actor state, so
 `authorize_query` gates the pruned answer the way it gates `snapshot`, and a
 caller the policy refuses reads `nil` for both.
 `retained_idempotency_keys` bounds the memory and defaults to 64 keys for each
-actor. Only a lookup by idempotency key can make the distinction. A request id
+actor, and `retained_idempotency_keys_bytes` bounds its serialized size at 16 KB,
+because an idempotency key has no length limit on every adapter and the memory
+outlives the message row. An actor drops its oldest keys until the list fits. Only a lookup by idempotency key can make the distinction. A request id
 is generated by the runtime rather than by the caller, so no actor remembers
 one, and `client.find_by(request_id:)` answers `nil` in both cases.
 

docs/operations.md

@@ -216,6 +216,7 @@ end
 | `process_retention` | 7 days |
 | `prune_batch_size` | 1,000 |
 | `retained_idempotency_keys` | 64 |
+| `retained_idempotency_keys_bytes` | 16 KB |
 | `worker_count` | 1 |
 | `effect_worker_count` | 1 |
 | `broadcast_worker_count` | 1 |
@@ -519,6 +520,7 @@ SolidObjects.configure do |configuration|
   configuration.process_retention = 7.days
   configuration.prune_batch_size = 1_000
   configuration.retained_idempotency_keys = 64
+  configuration.retained_idempotency_keys_bytes = 16.kilobytes
 end
 ```
 
@@ -556,6 +558,12 @@ keyed turns than that inside the window in which a caller may retry. A lookup
 by request id answers `nil` in both cases, so a caller that must tell them apart
 sends its own idempotency key.
 
+`retained_idempotency_keys_bytes` bounds the serialized memory as well, because
+an idempotency key has no length limit on every adapter and the memory outlives
+the message row. An actor drops its oldest keys until the list fits, so a key
+long enough to fill the limit by itself is never remembered and its lookup
+answers `nil` rather than raising.
+
 Actor expiration is disabled by default. `prune_instances` considers only
 actor types listed in `instance_retention_by_actor_type`, excludes active or
 paused actors, and preserves ready/claimed mailbox work, scheduled reminders,

lib/solid_objects/configuration.rb

@@ -32,6 +32,7 @@ class Configuration
     # @rbs @process_retention: Numeric
     # @rbs @prune_batch_size: Integer
     # @rbs @retained_idempotency_keys: Integer
+    # @rbs @retained_idempotency_keys_bytes: Integer
     # @rbs @redrive_batch_size: Integer
     # @rbs @redrive_batch_pause: Float
     # @rbs @worker_count: Integer
@@ -85,6 +86,7 @@ class Configuration
       :process_retention,
       :prune_batch_size,
       :retained_idempotency_keys,
+      :retained_idempotency_keys_bytes,
       :redrive_batch_size,
       :redrive_batch_pause,
       :worker_count,
@@ -143,6 +145,7 @@ def initialize
       @process_retention = 7.days
       @prune_batch_size = 1_000
       @retained_idempotency_keys = 64
+      @retained_idempotency_keys_bytes = 16.kilobytes
       @redrive_batch_size = 100
       @redrive_batch_pause = 0.05
       @worker_count = 1
@@ -315,6 +318,7 @@ def positive_values
         process_retention:,
         prune_batch_size:,
         retained_idempotency_keys:,
+        retained_idempotency_keys_bytes:,
         redrive_batch_size:
       }
     end

lib/solid_objects/executor.rb

@@ -489,7 +489,15 @@ def remembered_keys(instance, message)
       return remembered unless key
       return remembered if remembered.last == key
 
-      (remembered - [ key ] + [ key ]).last(SolidObjects.configuration.retained_idempotency_keys)
+      bounded(remembered - [ key ] + [ key ])
+    end
+
+    # @rbs (Array[String]) -> Array[String]
+    def bounded(keys)
+      kept = keys.last(SolidObjects.configuration.retained_idempotency_keys)
+      limit = SolidObjects.configuration.retained_idempotency_keys_bytes
+      kept.shift while kept.any? && kept.to_json.bytesize > limit
+      kept
     end
 
     # @rbs (Exception) -> Hash[String, untyped]

sig/generated/lib/solid_objects/configuration.rbs

@@ -2,71 +2,71 @@
 
 module SolidObjects
   class Configuration
-    @shutdown_timeout: Float
+    @transmission_actor_type_resolver: Proc
 
-    @supervisor_monitor_interval: Float
+    @broadcast_worker_count: Integer
 
-    @retention_interval: Float
+    @effect_worker_count: Integer
 
-    @dead_process_cleanup_interval: Float
+    @worker_count: Integer
 
-    @message_retention: Numeric
+    @redrive_batch_pause: Float
 
-    @message_retention_by_actor_type: Hash[String, Numeric]
+    @redrive_batch_size: Integer
 
-    @instance_retention_by_actor_type: Hash[String, Numeric]
+    @retained_idempotency_keys_bytes: Integer
 
-    @process_retention: Numeric
+    @retained_idempotency_keys: Integer
 
     @prune_batch_size: Integer
 
-    @retained_idempotency_keys: Integer
-
-    @redrive_batch_size: Integer
+    @process_retention: Numeric
 
-    @redrive_batch_pause: Float
+    @instance_retention_by_actor_type: Hash[String, Numeric]
 
-    @worker_count: Integer
+    @message_retention_by_actor_type: Hash[String, Numeric]
 
-    @effect_worker_count: Integer
+    @message_retention: Numeric
 
-    @broadcast_worker_count: Integer
+    @dead_process_cleanup_interval: Float
 
-    @reminder_scheduler_count: Integer
+    @retention_interval: Float
 
-    @connects_to: Hash[Symbol, untyped]?
+    @supervisor_monitor_interval: Float
 
-    @logger: untyped
+    @table_name_prefix: String
 
-    @stream_signing_secret: String?
+    @administration_identity: Proc
 
-    @broadcast_adapter: Proc?
+    @authorize_transmission: Proc
 
-    @wake_up_adapter: untyped
+    @authorize_administration: Proc
 
-    @component_path_resolver: Proc?
+    @authorize_subscription: Proc
 
-    @component_authorization_context: Proc
+    @authorize_destroy: Proc
 
-    @payload_authorization_context: Proc
+    @authorize_query: Proc
 
     @authorize_message: Proc
 
-    @authorize_query: Proc
+    @payload_authorization_context: Proc
 
-    @authorize_destroy: Proc
+    @component_authorization_context: Proc
 
-    @authorize_subscription: Proc
+    @component_path_resolver: Proc?
 
-    @authorize_administration: Proc
+    @wake_up_adapter: untyped
 
-    @authorize_transmission: Proc
+    @broadcast_adapter: Proc?
 
-    @administration_identity: Proc
+    @stream_signing_secret: String?
 
-    @transmission_actor_type_resolver: Proc
+    @logger: untyped
 
-    @table_name_prefix: String
+    @connects_to: Hash[Symbol, untyped]?
+
+    @reminder_scheduler_count: Integer
 
     @polling_interval: Float
 
@@ -106,6 +106,8 @@ module SolidObjects
 
     @process_alive_threshold: Float
 
+    @shutdown_timeout: Float
+
     attr_accessor table_name_prefix: untyped
 
     attr_accessor polling_interval: untyped
@@ -166,6 +168,8 @@ module SolidObjects
 
     attr_accessor retained_idempotency_keys: untyped
 
+    attr_accessor retained_idempotency_keys_bytes: untyped
+
     attr_accessor redrive_batch_size: untyped
 
     attr_accessor redrive_batch_pause: untyped

sig/generated/lib/solid_objects/executor.rbs

@@ -100,6 +100,9 @@ module SolidObjects
     # @rbs (Instance, Message) -> Array[String]
     def remembered_keys: (Instance, Message) -> Array[String]
 
+    # @rbs (Array[String]) -> Array[String]
+    def bounded: (Array[String]) -> Array[String]
+
     # @rbs (Exception) -> Hash[String, untyped]
     def serialized_error: (Exception) -> Hash[String, untyped]
 

test/integration/result_lookup_test.rb

@@ -294,6 +294,31 @@ def reject_checkout
     assert_raises(SolidObjects::MessagePruned) { reference.find_by(idempotency_key: "second") }
   end
 
+  test "bounds what an instance remembers by size" do
+    SolidObjects.configuration.retained_idempotency_keys_bytes = 64
+    reference = CartActor.ref("alice")
+    keys = 3.times.map { |index| "#{index}-#{"k" * 20}" }
+    keys.each_with_index { |key, index| reference.async(idempotency_key: key).checkout(order_id: index) }
+    run_actors
+
+    remembered = SolidObjects::Instance.sole.completed_idempotency_keys
+
+    assert_equal keys.last(2), remembered
+    assert_operator remembered.to_json.bytesize, :<=, 64
+  end
+
+  test "remembers nothing for a key larger than what it retains" do
+    SolidObjects.configuration.retained_idempotency_keys_bytes = 16
+    reference = CartActor.ref("alice")
+    key = "k" * 100
+    reference.async(idempotency_key: key).checkout(order_id: 1)
+    run_actors
+    SolidObjects::Message.delete_all
+
+    assert_empty SolidObjects::Instance.sole.completed_idempotency_keys
+    assert_nil reference.find_by(idempotency_key: key)
+  end
+
   test "remembers a re-sent key once" do
     reference = CartActor.ref("alice")
     reference.async(idempotency_key: "first").checkout(order_id: 1)