solid_objects 0.1.0

data/benchmark/support.rb

@@ -0,0 +1,271 @@
+# rbs_inline: enabled
+
+require "active_record"
+require "benchmark"
+require "fileutils"
+require "solid_objects"
+
+module SolidObjectsBenchmark
+  DATABASE_PATH = File.expand_path("../tmp/solid_objects_benchmark.sqlite3", __dir__)
+
+  class CounterActor < SolidObjects::Actor
+    actor_type "benchmark-counter"
+
+    attribute :count, default: 0
+
+    message :increment do
+      state.count += 1
+    end
+
+    query :count do
+      state.count
+    end
+  end
+
+  class << self
+    # @rbs () -> Integer
+    def count
+      Integer(ENV.fetch("COUNT", "500"))
+    end
+
+    # @rbs () -> Integer
+    def concurrency
+      Integer(ENV.fetch("CONCURRENCY", "4"))
+    end
+
+    # @rbs () -> void
+    def setup
+      establish_connection
+      migrate
+      load_models
+      SolidObjects.configuration.logger = Logger.new(nil)
+      SolidObjects.configuration.authorize_message = ->(**) { true }
+      SolidObjects.configuration.authorize_query = ->(**) { true }
+    end
+
+    # @rbs () -> void
+    def teardown
+      ActiveRecord::Base.connection_pool.disconnect!
+      FileUtils.rm_f(DATABASE_PATH) unless ENV["SOLID_OBJECTS_DATABASE_URL"]
+    end
+
+    # @rbs (String) { () -> untyped } -> Float
+    def measure(name)
+      elapsed = Benchmark.realtime { yield }
+      throughput = count / elapsed
+      puts "#{name}: #{format("%.3f", elapsed)}s, #{format("%.1f", throughput)} operations/s"
+      elapsed
+    end
+
+    # @rbs () -> void
+    def enqueue
+      reference = CounterActor.ref("enqueue")
+      measure("enqueue #{count} messages") do
+        count.times { reference.tell(:increment) }
+      end
+    end
+
+    # @rbs () -> void
+    def claim
+      count.times { |index| CounterActor.ref("claim-#{index}").tell(:increment) }
+      process_registry = SolidObjects::ProcessRegistry.new
+      owner_id = process_registry.register.id
+      activation_manager = SolidObjects::ActivationManager.new(owner_id:)
+      claimed_instance_ids = {}
+
+      measure("claim #{count} actors") do
+        count.times do
+          activation = activation_manager.claim_next
+          raise "actor was not claimable" unless activation
+          instance_id = activation.lease.instance_id
+          raise "actor was claimed twice" if claimed_instance_ids[instance_id]
+
+          claimed_instance_ids[instance_id] = true
+          SolidObjects::ReadyMessage.where(instance_id:).delete_all
+          activation.deactivate
+        end
+      end
+    ensure
+      process_registry&.stop
+    end
+
+    # @rbs () -> void
+    def processing
+      enqueue_round_robin
+      worker = SolidObjects::Worker.new
+      measure("process #{count} messages") { drain(worker) }
+    ensure
+      worker&.stop
+    end
+
+    # @rbs () -> void
+    def cold_actors
+      count.times { |index| CounterActor.ref("cold-#{index}").tell(:increment) }
+      worker = SolidObjects::Worker.new
+      measure("process #{count} cold actors") { drain(worker) }
+    ensure
+      worker&.stop
+    end
+
+    # @rbs () -> void
+    def hot_actor
+      reference = CounterActor.ref("hot")
+      count.times { reference.tell(:increment) }
+      worker = SolidObjects::Worker.new
+      measure("process #{count} messages for one hot actor") { drain(worker) }
+    ensure
+      worker&.stop
+    end
+
+    # @rbs () -> void
+    def concurrent_actors
+      enqueue_round_robin
+      workers = Array.new(concurrency) { SolidObjects::Worker.new }
+      measure("process #{count} messages with #{concurrency} workers") do
+        threads = workers.map { |worker| Thread.new { drain(worker) } }
+        threads.each(&:join)
+      end
+    ensure
+      workers&.each(&:stop)
+    end
+
+    # @rbs () -> void
+    def ask_latency
+      worker = SolidObjects::Worker.new
+      worker_thread = Thread.new { worker.run }
+      samples = []
+
+      count.times do |index|
+        started_at = monotonic_now
+        CounterActor.ref("ask-#{index}").ask(:count, timeout: 5)
+        samples << monotonic_now - started_at
+      end
+
+      sorted = samples.sort
+      puts "ask #{count} calls: p50=#{milliseconds(percentile(sorted, 0.50))}ms " \
+        "p95=#{milliseconds(percentile(sorted, 0.95))}ms " \
+        "p99=#{milliseconds(percentile(sorted, 0.99))}ms"
+    ensure
+      worker&.request_shutdown
+      worker_thread&.join
+    end
+
+    # @rbs () -> void
+    def activation_cache
+      reference = CounterActor.ref("cache")
+      count.times { reference.tell(:increment) }
+      activations = 0
+      subscriber = ActiveSupport::Notifications.subscribe("solid_objects.activation.started") do
+        activations += 1
+      end
+      worker = SolidObjects::Worker.new
+      processed = drain(worker)
+      hit_rate = processed.zero? ? 0.0 : 1.0 - (activations.to_f / processed)
+      puts "activation cache: #{processed} messages, #{activations} activations, " \
+        "#{format("%.1f", hit_rate * 100)}% reuse"
+    ensure
+      ActiveSupport::Notifications.unsubscribe(subscriber) if subscriber
+      worker&.stop
+    end
+
+    # @rbs () -> void
+    def query_count
+      CounterActor.ref("queries").tell(:increment)
+      worker = SolidObjects::Worker.new
+      queries = 0
+      subscriber = ActiveSupport::Notifications.subscribe("sql.active_record") do |event|
+        next if %w[SCHEMA TRANSACTION].include?(event.payload[:name])
+        next if event.payload[:cached]
+
+        queries += 1
+      end
+      processed = worker.run_once
+      puts "database queries: #{queries} for #{processed} message"
+    ensure
+      ActiveSupport::Notifications.unsubscribe(subscriber) if subscriber
+      worker&.stop
+    end
+
+    private
+
+    # @rbs () -> void
+    def establish_connection
+      database_url = ENV["SOLID_OBJECTS_DATABASE_URL"]
+      FileUtils.mkdir_p(File.dirname(DATABASE_PATH))
+      FileUtils.rm_f(DATABASE_PATH) unless database_url
+      ActiveRecord::Base.establish_connection(
+        database_url || {
+          adapter: "sqlite3",
+          database: DATABASE_PATH,
+          pool: concurrency + 5,
+          timeout: 5_000
+        }
+      )
+      ActiveRecord::Migration.verbose = false
+    end
+
+    # @rbs () -> void
+    def migrate
+      require_relative "../db/migrate/20260805000000_create_solid_objects_tables"
+      CreateSolidObjectsTables.new.migrate(:up)
+    end
+
+    # @rbs () -> void
+    def load_models
+      %w[
+        record
+        process
+        instance
+        message
+        ready_message
+        claimed_message
+        reminder
+        effect
+        broadcast
+        dead_letter
+      ].each do |model|
+        require_relative "../app/models/solid_objects/#{model}"
+      end
+    end
+
+    # @rbs () -> void
+    def enqueue_round_robin
+      actor_count = [ concurrency * 10, count ].min
+      references = Array.new(actor_count) { |index| CounterActor.ref("actor-#{index}") }
+      count.times { |index| references[index % actor_count].tell(:increment) }
+    end
+
+    # @rbs (SolidObjects::Worker) -> Integer
+    def drain(worker)
+      processed = 0
+      idle_passes = 0
+
+      while SolidObjects::ReadyMessage.exists? || SolidObjects::ClaimedMessage.exists?
+        pass_count = worker.run_once
+        processed += pass_count
+        idle_passes = pass_count.zero? ? idle_passes + 1 : 0
+        raise "benchmark made no progress" if idle_passes >= 1_000
+      end
+
+      processed
+    end
+
+    # @rbs () -> Float
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # @rbs (Array[Float], Float) -> Float
+    def percentile(samples, fraction)
+      samples.fetch(((samples.length - 1) * fraction).ceil)
+    end
+
+    # @rbs (Float) -> String
+    def milliseconds(seconds)
+      format("%.1f", seconds * 1_000)
+    end
+  end
+end
+
+SolidObjectsBenchmark.setup
+at_exit { SolidObjectsBenchmark.teardown }

data/config/routes.rb

@@ -0,0 +1,8 @@
+# rbs_inline: enabled
+
+SolidObjects::Engine.routes.draw do
+  resources :instances, only: %i[index show]
+  resources :dead_letters, only: %i[index] do
+    post :retry, on: :member
+  end
+end

data/db/migrate/20260805000000_create_solid_objects_tables.rb

@@ -0,0 +1,319 @@
+# rbs_inline: enabled
+
+class CreateSolidObjectsTables < ActiveRecord::Migration[8.0]
+  # @rbs () -> void
+  def change
+    create_processes
+    create_instances
+    create_messages
+    create_message_memberships
+    create_reminders
+    create_effects
+    create_broadcasts
+    create_dead_letters
+  end
+
+  private
+
+  # @rbs (Symbol) -> String
+  def table(name)
+    SolidObjects.table_name(name)
+  end
+
+  # @rbs () -> Symbol
+  def json_column_type
+    connection.adapter_name.match?(/postgres/i) ? :jsonb : :json
+  end
+
+  # @rbs (untyped, Symbol, ?null: bool) -> void
+  def json_column(definition, name, null: true)
+    definition.public_send(json_column_type, name, null:)
+  end
+
+  # @rbs () -> void
+  def create_processes
+    create_table table(:processes), id: :string, limit: 36 do |definition|
+      definition.string :kind, null: false, limit: 64
+      definition.string :hostname, null: false, limit: 255
+      definition.bigint :pid, null: false
+      definition.datetime :started_at, null: false, precision: 6
+      definition.datetime :last_heartbeat_at, null: false, precision: 6
+      json_column definition, :metadata, null: false
+      definition.string :shutdown_state, null: false, default: "running", limit: 32
+      definition.datetime :shutdown_requested_at, precision: 6
+      definition.datetime :stopped_at, precision: 6
+      definition.timestamps precision: 6, null: false
+
+      definition.index [ :shutdown_state, :last_heartbeat_at ], name: "idx_so_processes_liveness"
+      definition.index [ :kind, :shutdown_state ], name: "idx_so_processes_kind"
+      definition.check_constraint "shutdown_state IN ('running', 'draining', 'stopped')",
+        name: "chk_so_process_shutdown"
+    end
+  end
+
+  # @rbs () -> void
+  def create_instances
+    create_table table(:instances) do |definition|
+      definition.string :actor_type, null: false, limit: 191
+      definition.string :actor_id, null: false, limit: 191
+      json_column definition, :state, null: false
+      definition.integer :state_version, null: false, default: 1
+      definition.bigint :next_message_sequence, null: false, default: 1
+      definition.string :activation_owner_id, limit: 36
+      definition.datetime :activation_expires_at, precision: 6
+      definition.bigint :activation_generation, null: false, default: 0
+      definition.datetime :activated_at, precision: 6
+      definition.datetime :last_used_at, precision: 6
+      definition.datetime :last_claimed_at, precision: 6
+      definition.datetime :paused_at, precision: 6
+      definition.timestamps precision: 6, null: false
+
+      definition.index [ :actor_type, :actor_id ], unique: true, name: "idx_so_instances_identity"
+      definition.index [ :activation_expires_at, :last_claimed_at, :id ], name: "idx_so_instances_lease"
+      definition.index :activation_owner_id, name: "idx_so_instances_owner"
+      definition.index [ :last_used_at, :id ], name: "idx_so_instances_cleanup"
+      definition.check_constraint "state_version > 0", name: "chk_so_instances_state_version"
+      definition.check_constraint "next_message_sequence > 0", name: "chk_so_instances_sequence"
+      definition.check_constraint "activation_generation >= 0", name: "chk_so_instances_generation"
+    end
+
+    add_foreign_key table(:instances),
+      table(:processes),
+      column: :activation_owner_id,
+      on_delete: :nullify,
+      name: "fk_so_instances_owner"
+  end
+
+  # @rbs () -> void
+  def create_messages
+    create_table table(:messages) do |definition|
+      definition.references :instance,
+        null: false,
+        foreign_key: { to_table: table(:instances), on_delete: :cascade, name: "fk_so_messages_instance" }
+      definition.string :actor_type, null: false, limit: 191
+      definition.string :actor_id, null: false, limit: 191
+      definition.string :message_name, null: false, limit: 191
+      definition.string :message_kind, null: false, limit: 32
+      json_column definition, :arguments, null: false
+      definition.bigint :sequence, null: false
+      definition.integer :attempt_count, null: false, default: 0
+      definition.integer :max_attempts, null: false
+      definition.string :request_id, null: false, limit: 36
+      definition.string :idempotency_key, limit: 191
+      json_column definition, :result
+      json_column definition, :error
+      definition.datetime :enqueued_at, null: false, precision: 6
+      definition.datetime :available_at, null: false, precision: 6
+      definition.datetime :started_at, precision: 6
+      definition.datetime :completed_at, precision: 6
+      definition.datetime :last_failed_at, precision: 6
+      definition.timestamps precision: 6, null: false
+
+      definition.index [ :instance_id, :sequence ], unique: true, name: "idx_so_messages_instance_sequence"
+      definition.index [ :actor_type, :actor_id, :sequence ], unique: true, name: "idx_so_messages_actor_sequence"
+      definition.index :request_id, unique: true, name: "idx_so_messages_request"
+      definition.index [ :instance_id, :idempotency_key ], unique: true, name: "idx_so_messages_idempotency"
+      definition.index [ :completed_at, :id ], name: "idx_so_messages_cleanup"
+      definition.check_constraint "sequence > 0", name: "chk_so_messages_sequence"
+      definition.check_constraint "attempt_count >= 0", name: "chk_so_messages_attempt"
+      definition.check_constraint "max_attempts > 0", name: "chk_so_messages_max_attempts"
+      definition.check_constraint "message_kind IN ('tell', 'ask', 'internal')", name: "chk_so_messages_kind"
+    end
+  end
+
+  # @rbs () -> void
+  def create_message_memberships
+    create_table table(:ready_messages) do |definition|
+      definition.references :message,
+        null: false,
+        foreign_key: { to_table: table(:messages), on_delete: :cascade, name: "fk_so_ready_message" }
+      definition.references :instance,
+        null: false,
+        foreign_key: { to_table: table(:instances), on_delete: :cascade, name: "fk_so_ready_instance" }
+      definition.bigint :sequence, null: false
+      definition.datetime :available_at, null: false, precision: 6
+      definition.datetime :created_at, null: false, precision: 6
+
+      definition.index :message_id, unique: true, name: "idx_so_ready_message"
+      definition.index [ :instance_id, :sequence ], unique: true, name: "idx_so_ready_instance_sequence"
+      definition.index [ :available_at, :instance_id, :sequence ], name: "idx_so_ready_poll"
+      definition.check_constraint "sequence > 0", name: "chk_so_ready_sequence"
+    end
+
+    create_table table(:claimed_messages) do |definition|
+      definition.references :message,
+        null: false,
+        foreign_key: { to_table: table(:messages), on_delete: :cascade, name: "fk_so_claimed_message" }
+      definition.references :instance,
+        null: false,
+        foreign_key: { to_table: table(:instances), on_delete: :cascade, name: "fk_so_claimed_instance" }
+      definition.string :process_id, limit: 36
+      definition.bigint :activation_generation, null: false
+      definition.datetime :claimed_at, null: false, precision: 6
+
+      definition.index :message_id, unique: true, name: "idx_so_claimed_message"
+      definition.index :instance_id, unique: true, name: "idx_so_claimed_instance"
+      definition.index [ :process_id, :claimed_at ], name: "idx_so_claimed_process"
+      definition.check_constraint "activation_generation > 0", name: "chk_so_claimed_generation"
+    end
+
+    add_foreign_key table(:claimed_messages),
+      table(:processes),
+      column: :process_id,
+      on_delete: :nullify,
+      name: "fk_so_claimed_process"
+  end
+
+  # @rbs () -> void
+  def create_reminders
+    create_table table(:reminders) do |definition|
+      definition.references :instance,
+        null: false,
+        foreign_key: { to_table: table(:instances), on_delete: :cascade, name: "fk_so_reminders_instance" }
+      definition.string :actor_type, null: false, limit: 191
+      definition.string :actor_id, null: false, limit: 191
+      definition.string :name, null: false, limit: 191
+      definition.string :message_name, null: false, limit: 191
+      json_column definition, :arguments, null: false
+      definition.datetime :next_run_at, null: false, precision: 6
+      definition.decimal :interval_seconds, precision: 20, scale: 6
+      definition.bigint :occurrence, null: false, default: 0
+      definition.string :missed_policy, null: false, default: "latest", limit: 32
+      definition.string :status, null: false, default: "scheduled", limit: 32
+      definition.string :claimed_by, limit: 36
+      definition.datetime :claimed_at, precision: 6
+      definition.timestamps precision: 6, null: false
+
+      definition.index [ :instance_id, :name ], unique: true, name: "idx_so_reminders_name"
+      definition.index [ :status, :next_run_at, :id ], name: "idx_so_reminders_due"
+      definition.check_constraint "occurrence >= 0", name: "chk_so_reminders_occurrence"
+      definition.check_constraint "interval_seconds IS NULL OR interval_seconds > 0",
+        name: "chk_so_reminders_interval"
+      definition.check_constraint "missed_policy IN ('latest', 'all')",
+        name: "chk_so_reminders_missed"
+      definition.check_constraint "status IN ('scheduled', 'paused', 'completed')", name: "chk_so_reminders_status"
+    end
+
+    add_foreign_key table(:reminders),
+      table(:processes),
+      column: :claimed_by,
+      on_delete: :nullify,
+      name: "fk_so_reminders_process"
+  end
+
+  # @rbs () -> void
+  def create_effects
+    create_table table(:effects) do |definition|
+      definition.references :message,
+        null: false,
+        foreign_key: { to_table: table(:messages), on_delete: :cascade, name: "fk_so_effects_message" }
+      definition.references :instance,
+        null: false,
+        foreign_key: { to_table: table(:instances), on_delete: :cascade, name: "fk_so_effects_instance" }
+      definition.string :effect_id, null: false, limit: 36
+      definition.string :name, null: false, limit: 191
+      json_column definition, :arguments, null: false
+      definition.string :success_message_name, limit: 191
+      definition.string :failure_message_name, limit: 191
+      definition.string :status, null: false, default: "pending", limit: 32
+      definition.integer :attempt_count, null: false, default: 0
+      definition.integer :max_attempts, null: false
+      definition.datetime :available_at, null: false, precision: 6
+      definition.string :claimed_by, limit: 36
+      definition.datetime :claimed_at, precision: 6
+      json_column definition, :result
+      json_column definition, :error
+      definition.datetime :completed_at, precision: 6
+      definition.timestamps precision: 6, null: false
+
+      definition.index :effect_id, unique: true, name: "idx_so_effects_effect_id"
+      definition.index [ :status, :available_at, :id ], name: "idx_so_effects_poll"
+      definition.index [ :completed_at, :id ], name: "idx_so_effects_cleanup"
+      definition.check_constraint "attempt_count >= 0", name: "chk_so_effects_attempt"
+      definition.check_constraint "max_attempts > 0", name: "chk_so_effects_max_attempts"
+      definition.check_constraint "status IN ('pending', 'processing', 'completed', 'dead')", name: "chk_so_effects_status"
+    end
+
+    add_foreign_key table(:effects),
+      table(:processes),
+      column: :claimed_by,
+      on_delete: :nullify,
+      name: "fk_so_effects_process"
+  end
+
+  # @rbs () -> void
+  def create_broadcasts
+    create_table table(:broadcasts) do |definition|
+      definition.references :message,
+        null: false,
+        foreign_key: { to_table: table(:messages), on_delete: :cascade, name: "fk_so_broadcasts_message" }
+      definition.references :instance,
+        null: false,
+        foreign_key: { to_table: table(:instances), on_delete: :cascade, name: "fk_so_broadcasts_instance" }
+      definition.string :broadcast_id, null: false, limit: 36
+      definition.string :observable_name, null: false, limit: 191
+      json_column definition, :value, null: false
+      definition.integer :state_version, null: false
+      definition.bigint :activation_generation, null: false
+      definition.string :status, null: false, default: "pending", limit: 32
+      definition.integer :attempt_count, null: false, default: 0
+      definition.datetime :available_at, null: false, precision: 6
+      definition.string :claimed_by, limit: 36
+      definition.datetime :claimed_at, precision: 6
+      json_column definition, :error
+      definition.datetime :delivered_at, precision: 6
+      definition.timestamps precision: 6, null: false
+
+      definition.index :broadcast_id, unique: true, name: "idx_so_broadcasts_id"
+      definition.index [ :message_id, :observable_name ], unique: true, name: "idx_so_broadcasts_observable"
+      definition.index [ :status, :available_at, :id ], name: "idx_so_broadcasts_poll"
+      definition.index [ :claimed_by, :claimed_at ], name: "idx_so_broadcasts_claim"
+      definition.index [ :delivered_at, :id ], name: "idx_so_broadcasts_cleanup"
+      definition.check_constraint "state_version > 0", name: "chk_so_broadcasts_version"
+      definition.check_constraint "activation_generation > 0", name: "chk_so_broadcasts_generation"
+      definition.check_constraint "attempt_count >= 0", name: "chk_so_broadcasts_attempt"
+      definition.check_constraint "status IN ('pending', 'processing', 'delivered', 'dead')", name: "chk_so_broadcasts_status"
+    end
+
+    add_foreign_key table(:broadcasts),
+      table(:processes),
+      column: :claimed_by,
+      on_delete: :nullify,
+      name: "fk_so_broadcast_process"
+  end
+
+  # @rbs () -> void
+  def create_dead_letters
+    create_table table(:dead_letters) do |definition|
+      definition.references :message,
+        null: false,
+        foreign_key: { to_table: table(:messages), on_delete: :cascade, name: "fk_so_dead_letters_message" }
+      definition.references :instance,
+        null: false,
+        foreign_key: { to_table: table(:instances), on_delete: :cascade, name: "fk_so_dead_letters_instance" }
+      definition.string :actor_type, null: false, limit: 191
+      definition.string :actor_id, null: false, limit: 191
+      definition.string :message_name, null: false, limit: 191
+      json_column definition, :arguments, null: false
+      definition.integer :attempts, null: false
+      definition.string :exception_class, null: false, limit: 255
+      definition.text :exception_message, null: false
+      json_column definition, :backtrace, null: false
+      definition.datetime :first_failed_at, null: false, precision: 6
+      definition.datetime :last_failed_at, null: false, precision: 6
+      definition.bigint :retried_message_id
+      definition.timestamps precision: 6, null: false
+
+      definition.index :message_id, unique: true, name: "idx_so_dead_letters_message"
+      definition.index [ :actor_type, :actor_id, :last_failed_at ], name: "idx_so_dead_letters_actor"
+      definition.index [ :last_failed_at, :id ], name: "idx_so_dead_letters_cleanup"
+      definition.check_constraint "attempts > 0", name: "chk_so_dead_letters_attempts"
+    end
+
+    add_foreign_key table(:dead_letters),
+      table(:messages),
+      column: :retried_message_id,
+      on_delete: :nullify,
+      name: "fk_so_dead_letters_retry"
+  end
+end

data/docs/adr/0001-postgresql-backend.md

@@ -0,0 +1,21 @@
+# ADR 0001: PostgreSQL Is the Initial Backend
+
+- Status: Superseded by ADR 0013
+- Date: 2026-08-05
+
+## Context
+
+The runtime needs durable mailboxes, atomic state/message/outbox commits, concurrent worker claiming, small execution-membership tables, safe row locks, and fencing predicates. Supporting the least-common SQL feature set would weaken or complicate those guarantees.
+
+## Decision
+
+Solid Objects originally planned to support PostgreSQL only. It would use the host application's PostgreSQL environment by default and could use a separate Rails database configuration. Every table participating in one actor commit would be in the same database.
+
+This decision was superseded when the supported backend scope expanded to MySQL, PostgreSQL, and SQLite. PostgreSQL remains the optimized reference backend.
+
+## Consequences
+
+- Redis, Kafka, and a separate database server are not required.
+- SQLite and MySQL require their own verified coordination implementations.
+- PostgreSQL integration tests are part of correctness, not an optional adapter test.
+- Cross-database transactions are unsupported.

data/docs/adr/0002-jsonb-actor-state.md

@@ -0,0 +1,21 @@
+# ADR 0002: Actor State Uses Native JSON Storage
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+Actor state must be durable, inspectable, safely serialized, and evolvable without creating a table per actor type.
+
+## Decision
+
+Each actor instance stores one native JSON state document and an integer state version. PostgreSQL uses JSONB; MySQL uses JSON; SQLite uses the Rails JSON type over SQLite storage. State and all message-related values are limited to JSON-compatible primitives, arrays, and objects with string keys. Serialization is validated before persistence.
+
+Actors declare attributes, defaults, a current state version, and explicit one-step migrations. Migrations run in memory before a message executes and persist only with a successful fenced message commit.
+
+## Consequences
+
+- No `Marshal` or arbitrary object deserialization is allowed.
+- Large or query-heavy domain data should remain in normalized application tables, not actor state.
+- State migrations are application code and must remain compatible during rolling deployments.
+- Serializer extension points must still produce trusted JSON-compatible representations.

data/docs/adr/0003-mailbox-ordering.md

@@ -0,0 +1,30 @@
+# ADR 0003: Explicit Per-Actor Mailbox Sequences
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+Timestamps do not provide a unique order under concurrency. Independent message claims can also let later messages overtake an earlier retry.
+
+## Decision
+
+Every actor instance owns `next_message_sequence`. Enqueue runs in one transaction that locks or atomically updates the instance, allocates the next number, inserts the durable message, and inserts its ready-membership row. The database enforces uniqueness of actor identity plus sequence.
+
+Execution state is represented by table membership, not a status column:
+
+- `solid_objects_messages` is durable message history and contains the envelope, attempts, timestamps, result, and latest error.
+- `solid_objects_ready_messages` is the small hot set of messages eligible at `available_at`.
+- `solid_objects_claimed_messages` is the small set currently assigned to an activation owner and fencing generation.
+- `solid_objects_dead_letters` is the terminal failed set and diagnostic record.
+
+The earliest nonterminal sequence is the only eligible message for an actor. Moving a message between ready, claimed, and dead-letter membership occurs in short transactions that lock the durable message. A retryable failure moves the message back to ready with a later availability time and blocks later messages. A dead letter no longer blocks the mailbox.
+
+## Consequences
+
+- Concurrent enqueue has a deterministic committed order.
+- Sequence allocation is a per-actor serialization point.
+- Hot actors cannot increase enqueue throughput by adding workers.
+- Polling and claiming indexes stay proportional to live executable work, not completed history.
+- Cross-table membership is an application invariant maintained under message and activation locks because SQL cannot express one unique constraint across several tables.
+- Administrative retry of a dead letter creates a new mailbox message with a new sequence and links it to the dead letter.