solid_objects 0.1.0 → 0.2.1

data/docs/implementation-plan.md

@@ -161,7 +161,7 @@ Create the seven domain tables plus ready- and claimed-message membership tables
 
 The schema installs in PostgreSQL, MySQL, and SQLite dummy databases and database constraints reject invalid states independently of Rails validations.
 
-## Milestone 3: Durable enqueue, references, tell, and ask
+## Milestone 3: Durable enqueue and invocation modes
 
 ### Files
 
@@ -171,14 +171,15 @@ The schema installs in PostgreSQL, MySQL, and SQLite dummy databases and databas
 - `lib/solid_objects/message_reference.rb`
 - `lib/solid_objects/wake_up.rb`
 - `test/integration/enqueue_test.rb`
-- `test/integration/tell_test.rb`
-- `test/integration/ask_test.rb`
+- `test/integration/enqueue_test.rb`
+- `test/integration/sync_test.rb`
+- `test/integration/synchronous_invocation_test.rb`
 
 ### Public API
 
-- `Reference#tell`
-- `Reference#ask`
-- Method-style message, query, and read-only attribute dispatch
+- `Reference#async`
+- `Reference#sync`
+- Synchronous method-style message, query, and read-only attribute dispatch
 - `MessageReference#id`, `#status`, `#result`
 - Authorization context and hooks
 
@@ -191,8 +192,10 @@ No new tables. Use instance sequence and message request/idempotency columns.
 - Per-actor sequence allocation under concurrent connections
 - Independent sequences for different actors
 - Idempotency key deduplication
-- Tell return value
-- Ask success, failure, and timeout
+- Async return value
+- Synchronous success, rejection, failure, and timeout
+- Caller-assisted processing behind earlier asynchronous work
+- Same-actor serialization and different-actor concurrency
 - Mailbox and payload limits
 - Message/query authorization failure
 
@@ -201,12 +204,15 @@ No new tables. Use instance sequence and message request/idempotency columns.
 - Concurrent first enqueue
 - Lock timeout or deadlock
 - Duplicate idempotency key with different payload
-- Ask caller timeout
+- Synchronous caller timeout
 - Oversized payload or mailbox
 
 ### Completion criteria
 
-Messages and ready membership enqueue durably in strict per-actor sequence and `ask` can observe a manually completed result. Polling-only `ask` is documented as unsuitable for latency-sensitive request handlers.
+Messages and ready membership enqueue durably in strict per-actor sequence.
+Direct methods and `sync` claim and execute the actor locally when possible,
+while `async` returns immediately for worker execution. Every path uses the
+same mailbox, lease, fencing, and durable result.
 
 ## Milestone 4: Fenced, runnable vertical slice
 
@@ -236,7 +242,7 @@ No new tables.
 
 ### Tests
 
-- Shopping cart tell and ask
+- Shopping cart synchronous and asynchronous invocation
 - One actor processes messages sequentially
 - Different actors can execute concurrently
 - Lease acquire, renew, expire, and release
@@ -246,7 +252,7 @@ No new tables.
 - State and completion are atomic
 - Basic retry and strict head-of-mailbox blocking
 - Handler-level duplicate-delivery guards
-- Actor-to-actor tell outside actor context
+- Actor-to-actor asynchronous delivery
 
 ### Failure modes
 
@@ -325,7 +331,7 @@ Use the effects table. Add delivery-token or outcome columns only through a migr
 - Stable idempotency context
 - Success/failure outcome messages
 - Transactional actor-to-actor delivery
-- `ask` rejected in actor context
+- Direct and `sync` actor-to-actor calls rejected in actor context
 
 ### Failure modes
 
@@ -464,13 +470,13 @@ No expected changes.
 - Sensitive data in logs
 - Unbounded admin queries
 - Retrying wrong dead letter
-- Cleanup racing with ask waiter
-- Reconciliation code mutating actor state outside `tell`
+- Cleanup racing with a synchronous waiter
+- Reconciliation code mutating actor state outside `async`
 - Reconciliation stampedes without delayed `available_at`
 
 ### Completion criteria
 
-Operators can inspect health and failures without direct SQL, locate lost alarms and orphaned actors, and observe every required transition without raw arguments. Documentation requires reconciliation repairs to use delayed `tell` rather than direct instance updates.
+Operators can inspect health and failures without direct SQL, locate lost alarms and orphaned actors, and observe every required transition without raw arguments. Documentation requires reconciliation repairs to use delayed `async` delivery rather than direct instance updates.
 
 ## Milestone 10: Examples, benchmarks, documentation, and release hardening
 

data/docs/migrating-existing-state.md

@@ -0,0 +1,133 @@
+# Migrating existing state
+
+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.
+
+## 1. Write down the existing contract
+
+Inventory:
+
+- every read and write path;
+- the current canonical and secondary keys;
+- expiration and cleanup behavior;
+- concurrency guards and idempotency keys;
+- external effects;
+- expected request latency and volume; and
+- rollback requirements.
+
+Run the [fit checklist](fit.md#decision-checklist) before migrating. A hot
+counter or append pipeline may be better left in its existing store.
+
+## 2. Choose one canonical identity
+
+Solid Objects addresses an actor with one `(actor_type, actor_id)` pair. Do not
+hide two competing identities inside actor code or reintroduce a scan.
+
+When existing state is written by `(user_id, assessment_short)` but read by
+`session_id`, create a normalized lookup record:
+
+```ruby
+class AssessmentSession < ApplicationRecord
+  validates :session_id, uniqueness: true
+  validates :assessment_short, uniqueness: { scope: :user_id }
+
+  def actor
+    Assessment.ref(id)
+  end
+end
+```
+
+The lookup row gives both old keys one stable primary key. The actor ID is the
+lookup record ID, and ordinary indexed Active Record queries resolve either
+external key. This is clearer and safer than delimiter-joining composite values
+or preserving a `LIKE` scan.
+
+Create and backfill the lookup table before actor traffic begins. Enforce every
+identity invariant with unique database indexes.
+
+## 3. Add an idempotent bootstrap message
+
+Never bulk-update `solid_objects_instances.state`. Direct writes bypass actor
+ordering, state migrations, observables, activation ownership, and fencing.
+
+Import through a normal actor message:
+
+```ruby
+class Assessment < SolidObjects::Actor
+  attribute :imported, default: false
+  attribute :answers, default: -> { [] }
+
+  def bootstrap(answers:)
+    return if imported
+
+    self.answers = answers
+    self.imported = true
+  end
+end
+```
+
+Give every bootstrap call an idempotency key derived from the legacy record:
+
+```ruby
+session.actor.async(
+  :bootstrap,
+  answers: legacy.answers,
+  idempotency_key: "legacy-assessment:#{legacy.id}",
+  available_at: jittered_time
+)
+```
+
+Spread large backfills over a dispatch window and monitor mailbox age,
+failures, and dead letters. Asynchronous backfill requires the worker runtime.
+
+## 4. Prefer shadow comparison over blind dual writes
+
+Two independent stores cannot be updated atomically without a shared
+transaction or outbox. A controller that writes Redis and an actor in sequence
+can leave them divergent after a timeout or crash.
+
+A safer rollout:
+
+1. Keep the legacy store authoritative.
+2. Bootstrap the actor from a consistent legacy snapshot.
+3. Mirror new changes to the actor with stable idempotency keys.
+4. Read both stores in a background comparison path.
+5. Record divergence counts without changing the user response.
+6. Repair through actor messages, never direct actor-state SQL.
+7. Cut reads over only after divergence remains acceptably low.
+
+If the actor becomes authoritative before the legacy system is retired, emit a
+transactional effect that updates the legacy store. The effect is at least once,
+so the legacy write still needs idempotency.
+
+## 5. Cut over in reversible stages
+
+A typical zero-downtime sequence is:
+
+1. Deploy the lookup table and dual-key resolution.
+2. Deploy actor code and policies with reads still on the legacy store.
+3. Start the required runtime roles.
+4. Backfill actors in bounded batches.
+5. Enable shadow comparison and reconcile drift.
+6. Move a small cohort of reads to actors.
+7. Expand the cohort while watching latency, database growth, retries, and
+   divergence.
+8. Move writes to the actor.
+9. Retain the legacy state through an explicit rollback window.
+10. Remove dual writes and legacy data only after the rollback window closes.
+
+Use a feature flag whose rollback restores legacy reads and writes without
+requiring actor deletion. Do not assume a timed-out synchronous actor call did
+not commit; query the durable result or use an idempotency key before retrying.
+
+## 6. Plan for dormant state and future changes
+
+Actor state migrations and legacy-store migration solve different problems:
+
+- this cookbook moves ownership from another store into an actor;
+- `state_version` evolves actor JSON after that ownership exists.
+
+Keep every published actor migration step. A dormant actor can reactivate years
+later with an old state representation. See the
+[state migration guide](state-migrations.md) for rolling-deployment rules.

data/docs/operations.md

@@ -1,5 +1,20 @@
 # Operations guide
 
+## Installation verification
+
+Run the installation doctor after generating the initializer and migrating:
+
+```bash
+bin/rails solid_objects:doctor
+```
+
+It validates runtime configuration, required tables and columns, neutral policy
+posture, live runtime roles, and a real workerless synchronous actor round-trip.
+Engine migration timestamps are rewritten when copied into a host application,
+so the schema check compares the required shape instead of a fixed timestamp.
+Warnings such as an all-deny neutral policy do not fail the command because a
+context-aware production policy may correctly deny the probe.
+
 ## Runtime
 
 Start all configured roles:
@@ -61,7 +76,7 @@ operational task until that roadmap item lands.
 
 Self-scheduling actors need a daily or similarly low-frequency reconciliation
 job because an application-level alarm can be lost. The reconciler reads state
-but sends every repair through `tell`.
+but sends every repair through `async`.
 
 Use:
 
@@ -114,9 +129,46 @@ Alert on:
 ## Retention and backups
 
 The schema has cleanup indexes, but automatic pruning commands are still
-roadmap work. Until implemented, define application-owned bounded deletes that
-preserve unfinished messages, dead letters under investigation, and ask results
-for the promised lookup period.
+roadmap work. Every actor call creates a durable message-history row, including
+queries and attribute reads. Choose a retention period from measured call
+volume, storage budget, audit needs, and the longest promised synchronous-result
+lookup window.
+
+An application-owned pruning job can start from this conservative relation:
+
+```ruby
+cutoff = 30.days.ago
+
+prunable_messages = SolidObjects::Message
+  .where(completed_at: ...cutoff)
+  .where.not(id: SolidObjects::ReadyMessage.select(:message_id))
+  .where.not(id: SolidObjects::ClaimedMessage.select(:message_id))
+  .where.not(id: SolidObjects::DeadLetter.select(:message_id))
+  .where.not(
+    id: SolidObjects::DeadLetter
+      .where.not(retried_message_id: nil)
+      .select(:retried_message_id)
+  )
+  .where.not(
+    id: SolidObjects::Effect
+      .where.not(status: "completed")
+      .select(:message_id)
+  )
+  .where.not(
+    id: SolidObjects::Broadcast
+      .where.not(status: "delivered")
+      .select(:message_id)
+  )
+
+prunable_messages.in_batches(of: 1_000).delete_all
+```
+
+Deleting a message cascades to its completed effects, delivered broadcasts, and
+other message-owned records. Test the exact relation against a restored
+production snapshot before scheduling it. Keep source and retried messages for
+dead letters under investigation, and never prune pending, processing, ready, or
+claimed work. Choose a cutoff longer than every `sync` timeout because a caller
+whose result row disappears can no longer observe that result.
 
 Back up actor tables with the same consistency guarantees as application data.
 Restoring only instances without their mailboxes/outboxes, or vice versa, can

data/docs/research/solid_queue.md

@@ -82,7 +82,8 @@ The equivalent thin public surface is:
 
 - `SolidObjects::Actor` for definitions.
 - `ActorClass.ref(actor_id)` for logical addressing.
-- `SolidObjects::Reference#tell` and `#ask` for invocation.
+- Direct methods and `SolidObjects::Reference#sync` for request/response
+  invocation, plus `#async` for durable enqueue.
 - Explicit helpers for reminders, effects, observables, and lifecycle hooks.
 
 Mailbox rows, leases, worker records, and outboxes remain internal. Public message and dead-letter references should expose identifiers and safe inspection methods without leaking Active Record mutation APIs.

data/docs/roadmap.md

@@ -4,16 +4,21 @@
 
 - Rails engine, install generator, migration, and CLI
 - Explicit actor registry, references, JSON state, and state migrations
+- Direct synchronous RPC, explicit `sync`, and durable `async`
 - Durable message history plus ready/claimed membership tables
 - Concurrent sequence allocation and actor creation
-- Activation leases, renewal, generations, and fenced commits
+- Activation leases, renewal, unique activation tokens, generations, and
+  fenced commits
 - Bounded activation passes, idle cache, hot-actor yield, and process records
-- At-least-once retries, strict poison ordering, dead letters, and tail retry
+- At-least-once retries, terminal domain rejection, strict poison ordering,
+  dead letters, and tail retry
 - Transactional effects with success/failure actor messages
 - Actor-to-actor asynchronous outbox delivery
 - One-shot and recurring reminders with `:latest` or `:all` catch-up
 - Durable observable broadcast outbox and authorized Action Cable refresh
 - Reconciliation read APIs
+- Installation doctor, authorization reference, fit guide, and legacy-state
+  migration cookbook
 - SQLite, PostgreSQL, and MySQL integration suites
 - Inline RBS generation/validation, Steep, Standard Ruby, Solid Queue's exact
   RuboCop policy, and a warning-free Brakeman scan
@@ -47,7 +52,8 @@
    eviction.
 8. Expand security scanning and run compatibility CI across supported Rails and
    Ruby versions.
-9. Benchmark all workloads under documented hardware/database settings.
+9. Benchmark all workloads under documented hardware/database settings and
+   publish adapter-specific adoption measurements.
 
 No production-ready claim should be made until these hardening milestones have
 operational soak evidence.

data/docs/security.md

@@ -7,10 +7,15 @@ destroying actors, subscribing to actor streams, and administration. The host
 application supplies the authenticated request or connection as
 `authorization_context`. All five hooks deny by default.
 
+The [authorization reference](authorization.md) lists the caller context and
+risk for every hook and includes a tenant-aware policy example.
+
 Method-style reference calls do not bypass these hooks. Public instance methods
 declared on an actor are part of its remotely addressable message surface and
-delegate to the authorized `tell` path. Keep implementation helpers private or
-protected. Query and attribute methods delegate to the authorized `ask` path.
+delegate to the authorized synchronous invocation path. Keep implementation
+helpers private or protected. Query and attribute methods use the separate
+query authorization policy. Explicit `async` message delivery uses the same
+message authorization policy as direct calls.
 `reference.destroy` delegates to `authorize_destroy` before checking whether
 the actor exists, so denial does not reveal actor existence.
 

data/docs/state-migrations.md

@@ -44,3 +44,7 @@ A safe destructive rollout normally uses:
 
 Never update actor JSON in a bulk SQL migration. Use actor messages so fencing,
 ordering, observables, and outboxes remain intact.
+
+This guide covers evolution after state belongs to Solid Objects. For moving
+existing Redis, key-value, or relational state into actors without downtime,
+use the [legacy-state migration cookbook](migrating-existing-state.md).

data/lib/generators/solid_objects/templates/solid_objects.rb

@@ -5,6 +5,23 @@ SolidObjects.configure do |configuration|
   configuration.effect_worker_count = 1
   configuration.broadcast_worker_count = 1
   configuration.reminder_scheduler_count = 1
+
+  # Every policy denies by default, so a fresh installation is intentionally
+  # inert. Replace these policies before invoking actors.
+  #
+  # Message and query policies gate direct calls, sync, async, and state reads.
+  # Destroy removes an actor and all of its durable work. Subscription gates
+  # Action Cable streams. Administration gates engine pages and operational
+  # commands. Keep the last three denied until their callers are authenticated.
+  #
+  # Prefer policies that bind actor_type and actor_id to a trusted
+  # authorization_context. See:
+  # https://github.com/cardmagic/solid_objects/blob/main/docs/authorization.md
+  # and run:
+  #
+  #   bin/rails solid_objects:doctor
+  #
+  # after configuring the application.
   configuration.authorize_message = ->(**) { false }
   configuration.authorize_query = ->(**) { false }
   configuration.authorize_destroy = ->(**) { false }

data/lib/solid_objects/activation.rb

@@ -31,26 +31,12 @@ module SolidObjects
 
     # @rbs () -> Integer
     def drain
-      processed_count = 0
-      started_at = monotonic_now
-      @pass_exhausted = false
-
-      loop do
-        if processed_count >= SolidObjects.configuration.max_messages_per_activation_pass ||
-            monotonic_now - started_at >= SolidObjects.configuration.max_activation_duration
-          @pass_exhausted = true
-          break
-        end
-
-        message = claim_next_message
-        break unless message
-
-        Executor.new(activation: self, message:).call
-        processed_count += 1
-        @last_used_at = monotonic_now
-      end
+      drain_messages
+    end
 
-      processed_count
+    # @rbs (message_id: Integer, deadline: Float) -> Integer
+    def drain_until(message_id:, deadline:)
+      drain_messages(message_id:, deadline:)
     end
 
     # @rbs () -> bool
@@ -60,6 +46,7 @@ module SolidObjects
         ClaimedMessage.where(
           instance_id: lease.instance_id,
           process_id: lease.owner_id,
+          activation_token: lease.activation_token,
           activation_generation: lease.generation
         ).exists?
     end
@@ -113,6 +100,33 @@ module SolidObjects
 
     attr_reader :actor_class
 
+    # @rbs (?message_id: Integer?, ?deadline: Float?) -> Integer
+    def drain_messages(message_id: nil, deadline: nil)
+      processed_count = 0
+      started_at = monotonic_now
+      @pass_exhausted = false
+
+      loop do
+        break if deadline && monotonic_now >= deadline
+
+        if processed_count >= SolidObjects.configuration.max_messages_per_activation_pass ||
+            monotonic_now - started_at >= SolidObjects.configuration.max_activation_duration
+          @pass_exhausted = true
+          break
+        end
+
+        message = claim_next_message
+        break unless message
+
+        Executor.new(activation: self, message:).call
+        processed_count += 1
+        @last_used_at = monotonic_now
+        break if message.id == message_id
+      end
+
+      processed_count
+    end
+
     # @rbs (Instance) -> Actor
     def build_actor(instance)
       state_data = actor_class.definition.migrate_state(instance.state_version, instance.state)
@@ -145,6 +159,7 @@ module SolidObjects
           message:,
           instance:,
           process_id: lease.owner_id,
+          activation_token: lease.activation_token,
           activation_generation: lease.generation,
           claimed_at: now
         )
@@ -161,6 +176,7 @@ module SolidObjects
         .first
       return unless claimed_message
       return if claimed_message.process_id == lease.owner_id &&
+        claimed_message.activation_token == lease.activation_token &&
         claimed_message.activation_generation == lease.generation
 
       message = claimed_message.message

data/lib/solid_objects/activation_manager.rb

@@ -13,17 +13,37 @@ module SolidObjects
 
     # @rbs () -> Activation?
     def claim_next
+      claim_from(candidate_instance_ids(database_adapter.database_now))
+    end
+
+    # @rbs (instance_id: Integer) -> Activation?
+    def claim(instance_id:)
+      claim_from([ instance_id ])
+    end
+
+    private
+
+    attr_reader :owner_id, :database_adapter
+
+    # @rbs (Array[Integer]) -> Activation?
+    def claim_from(instance_ids)
       lease = database_adapter.transaction do
         now = database_adapter.database_now
         claimed_lease = nil
-        candidate_instance_ids(now).each do |instance_id|
+        instance_ids.each do |instance_id|
           instance = database_adapter.lock_candidates(
             Instance.where(id: instance_id)
           ).first
           next unless instance
           next unless claimable?(instance, now)
 
-          claimed_lease = Lease.claim(instance:, owner_id:, now:, database_adapter:)
+          claimed_lease = Lease.claim(
+            instance:,
+            owner_id:,
+            activation_token: SecureRandom.uuid,
+            now:,
+            database_adapter:
+          )
           break if claimed_lease
         end
         claimed_lease
@@ -42,10 +62,6 @@ module SolidObjects
       raise
     end
 
-    private
-
-    attr_reader :owner_id, :database_adapter
-
     # @rbs (Time) -> Array[Integer]
     def candidate_instance_ids(now)
       (ready_instance_ids(now) + claimed_instance_ids(now)).uniq

data/lib/solid_objects/actor.rb

@@ -150,7 +150,17 @@ module SolidObjects
       Context.current_message
     end
 
-    # @rbs (Symbol | String, ?on_success: Symbol | String?, ?on_failure: Symbol | String?, **untyped) -> EffectIntent
+    # @rbs (Symbol | String, String, ?details: Hash[String | Symbol, untyped]) -> bot
+    def reject(code, message, details: {})
+      rejection_code = code.to_s
+      unless rejection_code.match?(/\A[a-z][a-z0-9_]*\z/)
+        raise ArgumentError, "rejection code must contain lowercase letters, digits, and underscores"
+      end
+
+      raise Rejected.new(code: rejection_code, message:, details:)
+    end
+
+    # @rbs (Symbol | String, ?on_success: Symbol | String?, ?on_failure: Symbol | String?, **untyped) -> nil
     def emit(name, on_success: nil, on_failure: nil, **arguments)
       validate_effect_callback!(on_success)
       validate_effect_callback!(on_failure)
@@ -162,9 +172,10 @@ module SolidObjects
       ).tap do |intent|
         effect_intents << intent
       end
+      nil
     end
 
-    # @rbs (Symbol | String, at: Time, ?every: Numeric?, ?missed: Symbol | String, arguments: Hash[Symbol | String, untyped]) -> ReminderIntent
+    # @rbs (Symbol | String, at: Time, ?every: Numeric?, ?missed: Symbol | String, arguments: Hash[Symbol | String, untyped]) -> nil
     def schedule(name, at:, every: nil, missed: :latest, arguments: {})
       interval_seconds = every&.to_f
       if interval_seconds && !interval_seconds.positive?
@@ -184,11 +195,13 @@ module SolidObjects
       ).tap do |intent|
         reminder_intents << intent
       end
+      nil
     end
 
-    # @rbs (Reference, Symbol | String, ?available_at: Time?, ?idempotency_key: String?, **untyped) -> OutboundMessageIntent
+    # @rbs (Reference, Symbol | String, ?available_at: Time?, ?idempotency_key: String?, **untyped) -> nil
     def send_to(reference, message_name, available_at: nil, idempotency_key: nil, **arguments)
       stage_outbound_message(reference, message_name, arguments, available_at:, idempotency_key:)
+      nil
     end
 
     # @rbs (Symbol | String, Hash[String, untyped]) -> untyped

data/lib/solid_objects/caller_process.rb

@@ -0,0 +1,57 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class CallerProcess
+    # @rbs @mutex: Thread::Mutex
+    # @rbs @process_id: Integer?
+    # @rbs @registry: ProcessRegistry?
+
+    # @rbs () -> void
+    def initialize
+      @mutex = Thread::Mutex.new
+      @process_id = nil
+      @registry = nil
+    end
+
+    # @rbs () -> ProcessRegistry
+    def process_registry
+      mutex.synchronize do
+        reset_after_fork
+        register unless reusable_registry?
+        registry.heartbeat
+        registry
+      end
+    end
+
+    private
+
+    attr_reader :mutex, :registry
+
+    # @rbs () -> void
+    def reset_after_fork
+      return if @process_id == ::Process.pid
+
+      @process_id = ::Process.pid
+      @registry = nil
+    end
+
+    # @rbs () -> bool
+    def reusable_registry?
+      return false unless registry&.process_record
+
+      registry.process_record.reload.shutdown_state == "running"
+    rescue ActiveRecord::RecordNotFound
+      false
+    end
+
+    # @rbs () -> ProcessRegistry
+    def register
+      @registry = ProcessRegistry.new
+      registry.register(
+        kind: "caller",
+        metadata: { execution: "synchronous" }
+      )
+      registry
+    end
+  end
+end