solid_objects 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d95ae7c1b6791ce00951e73eaf535a7b0b357c6708112509544de82eb59314d
-  data.tar.gz: a6a9ef715c217e38959438d1ab549447e0814c621746967dece190ae46b3108b
+  metadata.gz: 654720ae19caa970f403b5cded61287e1f6a9eb9d731ff90fd9f4f103d55fa53
+  data.tar.gz: 256712423dd88685643a0345de44eb774efbca12188c78c9e89571ef884b59fc
 SHA512:
-  metadata.gz: d604e195d678ae5f2ae24932fd0431a7076d0f8258b9e064bbc463042b911512edc7a6b613673b6731256d0b0603311708beb2158d79e421dc85b5febfb37f4d
-  data.tar.gz: cd817466462c8d0c843fa9766df1f2190ed3b477466661e32a47859f7fc63349327af7cb077d75ab5a43b621bb3ee98e321363b007ff5ad19e311123d871e040
+  metadata.gz: f1e43da5f13c33558bdb187b52c55b55093786d3ec8af9f49d4ffc123ade274d2f5483dd8975c6a638152dfc9ae1c4cf416d8b1ea94cb1383ac30b33ef7548aa
+  data.tar.gz: f8cb10850b5b3748450ffaf741417866ed360437657c5d21836312018f0d6b27109cd69c4035f770f6cf643227ab086ae7eedc1b0a14245103cfe517a008f49c

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.1 - 2026-08-06
+
+- Add `solid_objects:doctor` for configuration, schema, policy, runtime, and
+  workerless synchronous round-trip verification.
+- Add onboarding guidance for fit decisions, worker requirements,
+  authorization, performance and row growth, retention, Sorbet, RuboCop, and
+  migrations from existing state stores.
+- Make the early-Action View engine boot regression explicit.
+
 ## 0.2.0 - 2026-08-06
 
 - Make direct actor methods synchronous Durable Object-style RPC.

data/README.md

@@ -20,8 +20,13 @@ class Counter < SolidObjects::Actor
   end
 end
 
-# from anywhere in your app — addressed by name:
-Counter.ref("global").increment(amount: 5)
+# Synchronous caller-assisted RPC. No worker fleet is required.
+counter = Counter.ref("global")
+count = counter.increment(amount: 5)
+current_count = counter.value
+
+# Durable fire-and-forget delivery. A worker processes it later.
+message = counter.async(:increment, amount: 5)
 ```
 
 `Counter / global` is a logical identity. Like a Durable Object named with
@@ -30,6 +35,23 @@ locating a Ruby object. Solid Objects activates it when work arrives, commits
 its ordered turns one at a time, persists its state, and deactivates it when
 idle. Different identities can run concurrently.
 
+The invocation model is the first adoption decision:
+
+| Call | Returns | Worker fleet required? |
+| --- | --- | --- |
+| `counter.increment(amount: 5)` | Committed handler result | No |
+| `counter.sync(:increment, amount: 5)` | Committed handler result | No |
+| `counter.value` | Deeply frozen state snapshot | No |
+| `counter.async(:increment, amount: 5)` | `MessageReference` immediately | Yes |
+
+Direct methods and `sync` durably enqueue the call, then the Rails caller helps
+execute the actor through the same mailbox, lease, and fencing path as a
+worker. `async` only enqueues; a runtime process handles it later.
+
+Before adopting a latency-sensitive or high-volume surface, read
+[Is Solid Objects a good fit?](docs/fit.md) and the
+[measured performance and row-growth costs](docs/benchmarks.md).
+
 This is a port of the programming model, not Cloudflare's edge runtime or
 platform. Read the conceptual overview at [solidobjects.dev](https://solidobjects.dev/)
 and the exact Rails guarantees in [Correctness and delivery semantics](docs/correctness.md).
@@ -43,6 +65,7 @@ but the project does not yet claim production readiness. See
 - [Cloudflare Durable Objects for Rails](#cloudflare-durable-objects-for-rails)
 - [Reactive ERB](#reactive-erb)
 - [Installation](#installation)
+- [Worker requirements](#worker-requirements)
 - [Defining an actor](#defining-an-actor)
 - [Actor identity](#actor-identity)
 - [Invoking an object](#invoking-an-object)
@@ -187,10 +210,17 @@ Add the gem, install its initializer and migration, then migrate:
 bundle add solid_objects
 bin/rails generate solid_objects:install
 bin/rails db:migrate
+bin/rails solid_objects:doctor
 ```
 
-The generated initializer denies all externally initiated operations. Replace
-the policy blocks with application-specific authorization before sending
+The doctor validates configuration and required schema shape, reports
+authorization posture and live runtime roles, and completes a real synchronous
+actor round-trip without a worker. It checks required tables and columns instead
+of a copied migration timestamp, which the host application rewrites. It exits
+unsuccessfully when configuration, schema, or the round-trip is broken.
+
+The generated initializer is intentionally inert: all five policies deny by
+default. Replace them with application-specific authorization before sending
 messages, querying state, destroying actors, subscribing to streams, or
 mounting administration routes:
 
@@ -205,16 +235,62 @@ end
 ```
 
 Knowledge of an actor ID or signed stream token is never authorization.
+Read the [policy reference and tenant-aware example](docs/authorization.md)
+before opening a policy. Unconditionally allowing message and query calls is
+reasonable only for a controlled server-side pilot. Keep destroy,
+subscription, and administration denied until each has an authenticated
+caller.
 
-Start the runtime for asynchronous messages, effects, reminders, and
-broadcasts:
+The engine uses the application's primary Active Record connection by default.
+See [Database support](#database-support) for a separate database configuration.
+
+### Host application tooling
+
+Installed engine migrations are copied as
+`db/migrate/*_create_solid_objects_tables.solid_objects.rb`. If the host enables
+`Rails/CreateTableWithTimestamps`, exclude engine-owned migrations rather than
+editing their intentionally specialized hot tables:
+
+```yaml
+Rails/CreateTableWithTimestamps:
+  Exclude:
+    - "db/migrate/*.solid_objects.rb"
+```
+
+Solid Objects ships inline RBS signatures, not RBI files. Sorbet applications
+can generate the gem RBI with:
+
+```bash
+bundle exec tapioca gem solid_objects
+```
+
+## Worker requirements
+
+Synchronous actors can be adopted without adding a long-running process. Start
+the runtime when the feature introduces asynchronous delivery or outboxes:
+
+| Feature | Runtime roles required |
+| --- | --- |
+| Direct actor method or explicit `sync` | None; the caller executes it |
+| Attribute or declared query read | None; the caller executes it |
+| `destroy` | None |
+| `async` including delayed delivery | Actor worker |
+| One-shot or recurring `schedule` | Reminder scheduler and actor worker |
+| `emit` without an actor callback | Effect worker |
+| `emit` with success or failure callback | Effect worker and actor worker |
+| Actor-to-actor `async` or `send_to` | Effect worker and actor worker |
+| Observable Turbo updates | Broadcast worker, Action Cable, and the actor execution path |
+| Initial `solid_object` server render | No Solid Objects worker; normal Rails rendering |
+
+One command starts every Solid Objects role:
 
 ```bash
 bundle exec solid_objects start
 ```
 
-The engine uses the application's primary Active Record connection by default.
-See [Database support](#database-support) for a separate database configuration.
+Deploy and monitor that process before enabling any feature marked as requiring
+a runtime role. A missing worker never makes a durable `async` message
+disappear, but it leaves the message pending indefinitely.
 
 ## Defining an actor
 
@@ -396,6 +472,10 @@ The caller receives `SolidObjects::Rejected` with a stable code, message, and
 JSON-compatible details. The rejected message remains durable for audit, actor
 state is rolled back, and no later mailbox turn is blocked.
 
+`Rejected#code` is a `String`, even when `reject` receives a symbol. Codes must
+match `\A[a-z][a-z0-9_]*\z`; invalid codes raise `ArgumentError` when the
+handler calls `reject`.
+
 ### Redelivery
 
 Sequential does not mean once. A handler can run again after a process crash or
@@ -686,6 +766,13 @@ Do not use it for stateless work, bulk pipelines, CPU-heavy computation,
 cross-actor transactions, slow network calls inside handlers, or domains that
 are clearer as normalized Active Record models and direct service objects.
 
+High-QPS request reads, rate-limit counters, impression pipelines, large JSON
+documents, and latency budgets that cannot tolerate several coordination
+transactions are explicit anti-patterns. Read the full
+[fit and anti-pattern guide](docs/fit.md) before migrating an existing
+surface, and use the [legacy-state migration cookbook](docs/migrating-existing-state.md)
+for staged cutovers.
+
 ## Comparisons
 
 | Tool | What Solid Objects adds or changes |

data/benchmark/adoption_latency.rb

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

data/benchmark/support.rb

@@ -145,6 +145,32 @@ module SolidObjectsBenchmark
         "p99=#{milliseconds(percentile(sorted, 0.99))}ms"
     end
 
+    # @rbs () -> void
+    def adoption_latency
+      instance_count = SolidObjects::Instance.count
+      message_count = SolidObjects::Message.count
+
+      cold_elapsed = Benchmark.realtime do
+        CounterActor.ref("adoption-cold").increment
+      end
+
+      reference = CounterActor.ref("adoption-warm")
+      reference.increment
+      write_samples = Array.new(count) do
+        Benchmark.realtime { reference.increment }
+      end
+      read_samples = Array.new(count) do
+        Benchmark.realtime { reference.count }
+      end
+
+      puts "first cold call: #{milliseconds(cold_elapsed)}ms"
+      puts latency_summary("warm writes", write_samples)
+      puts latency_summary("ordered reads", read_samples)
+      puts "durable row growth: " \
+        "instances=+#{SolidObjects::Instance.count - instance_count}, " \
+        "messages=+#{SolidObjects::Message.count - message_count}"
+    end
+
     # @rbs () -> void
     def activation_cache
       reference = CounterActor.ref("cache")
@@ -255,6 +281,15 @@ module SolidObjectsBenchmark
       samples.fetch(((samples.length - 1) * fraction).ceil)
     end
 
+    # @rbs (String, Array[Float]) -> String
+    def latency_summary(name, samples)
+      sorted = samples.sort
+      "#{name} #{samples.length} calls: " \
+        "median=#{milliseconds(percentile(sorted, 0.50))}ms " \
+        "min=#{milliseconds(sorted.first)}ms " \
+        "max=#{milliseconds(sorted.last)}ms"
+    end
+
     # @rbs (Float) -> String
     def milliseconds(seconds)
       format("%.1f", seconds * 1_000)

data/docs/authorization.md

@@ -0,0 +1,85 @@
+# 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.
+
+## Policy reference
+
+| Policy | Gates | Caller context | Risk if opened globally |
+| --- | --- | --- | --- |
+| `authorize_message` | Direct actor methods, explicit `sync` messages, and public `async` enqueue | Value passed as `authorization_context:`; often a user, service principal, or trusted internal marker | Anyone reaching the call site can mutate any known actor identity |
+| `authorize_query` | Attribute reads, declared queries, observable reads, and component reads | Explicit call context or the Rails view context supplied by `solid_object` | Actor state can leak across users or tenants |
+| `authorize_destroy` | `reference.destroy` | Value passed as `authorization_context:` | Complete actor state, mailbox, reminders, and pending outboxes can be deleted |
+| `authorize_subscription` | Action Cable subscription to one actor stream | The `ActionCable::Connection` object | Clients can receive future observable updates for other actors |
+| `authorize_administration` | Engine administration controllers, process inspection/cleanup, and dead-letter inspection/retry | Rails controller or `{ source: "cli" }` | Operational metadata, arguments, errors, and retries become exposed or mutable |
+
+Internal reminder, effect-callback, and actor-to-actor deliveries come from
+already committed runtime rows and do not re-enter the public client policy.
+
+## A tenant-aware policy
+
+Pass the authenticated user as the call context:
+
+```ruby
+cart = ShoppingCart.ref(Current.user.id)
+cart.add_item(
+  product_id: "shirt-123",
+  authorization_context: Current.user
+)
+```
+
+Authorize only the matching user and actor type:
+
+```ruby
+SolidObjects.configure do |configuration|
+  owns_actor = lambda do |actor_type:, actor_id:, authorization_context:, **|
+    user = authorization_context
+
+    actor_type == "ShoppingCart" &&
+      user.present? &&
+      actor_id == user.id.to_s
+  end
+
+  configuration.authorize_message = owns_actor
+  configuration.authorize_query = owns_actor
+  configuration.authorize_destroy = owns_actor
+
+  configuration.authorize_subscription = lambda do |actor_type:, actor_id:, authorization_context:|
+    connection = authorization_context
+
+    actor_type == "ShoppingCart" &&
+      connection.current_user.present? &&
+      actor_id == connection.current_user.id.to_s
+  end
+
+  configuration.authorize_administration = lambda do |authorization_context:, **|
+    context = authorization_context
+    user = context.respond_to?(:current_user) ? context.current_user : nil
+
+    user&.administrator?
+  end
+end
+```
+
+The policy receives normalized actor type and ID strings, message name and
+arguments where relevant, and the context supplied by the caller. Avoid
+authorizing from arguments alone; bind the actor identity to the authenticated
+principal and tenant.
+
+## Server-side-only pilots
+
+Allowing `authorize_message` and `authorize_query` unconditionally can be a
+reasonable short-lived pilot only when every call site is trusted server code,
+actor IDs cannot come from an unauthorized request, and the feature is not
+exposed through Action Cable or administration routes.
+
+Keep `authorize_destroy`, `authorize_subscription`, and
+`authorize_administration` denied until each feature has an explicit policy.
+Replace unconditional policies before exposing actor IDs to controllers, API
+clients, MCP tools, jobs carrying user input, or browser subscriptions.
+
+Run `bin/rails solid_objects:doctor` after configuration. Its neutral policy
+probe is deliberately conservative: a context-aware policy may correctly warn
+because it denies a `nil` context.

data/docs/benchmarks.md

@@ -1,10 +1,31 @@
-# Local benchmarks
+# 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
 contention.
 
+## Production-shaped adoption measurement
+
+An adoption evaluation measured Solid Objects 0.2.0 from a macOS Rails process
+against Docker MySQL 8 over a published TCP port. The host used Rails 8.1, Ruby
+4.0.5, roughly 165 gems, and an approximately 2,200-line schema.
+
+| Operation | Existing key-value row | Solid Objects |
+| --- | ---: | ---: |
+| Write | median 4.7 ms | median 60 ms, minimum 33 ms, maximum 163 ms |
+| Read | median 0.2 ms | median 28 ms |
+| First call for a cold identity | approximately 5 ms | 315 ms |
+
+This is not a controlled cross-database benchmark and no sample count was
+recorded. It is still useful adoption evidence: a synchronous actor call is not
+a substitute for a direct indexed row read when single-digit-millisecond
+latency is the requirement. The first call includes actor-instance creation,
+caller-process registration, message enqueue, activation claim, handler
+execution, fenced commit, and activation release.
+
+## Project development benchmark
+
 Measured 2026-08-06 on an Apple M5 with 24 GB RAM, Ruby 4.0.5, Rails 8.1.3.1,
 and SQLite 3.51.0. Each throughput scenario used 200 operations; the concurrent
 scenario used four worker threads.
@@ -21,6 +42,55 @@ scenario used four worker threads.
 | Activation reuse | 98.0%, four activations for 200 messages |
 | Queries for one message turn | 29 |
 
+The difference between the SQLite development result and the MySQL adoption
+result is why Solid Objects does not publish one latency promise. Network
+topology, adapter behavior, host schema, logging, callbacks, and contention all
+matter.
+
+## Durable row growth
+
+The storage cost is deterministic even when latency is not:
+
+- the first call for one actor identity inserts one
+  `solid_objects_instances` row;
+- every direct, `sync`, query, attribute read, or `async` call inserts one
+  permanent `solid_objects_messages` row;
+- ready and claimed membership rows exist only while the call is pending or
+  executing;
+- one caller process row is registered per application process that performs
+  synchronous calls;
+- effects and observable changes add outbox rows; and
+- reminders add one row per named actor reminder.
+
+Attribute reads are therefore not free snapshots from the instance row. They
+are ordered durable query messages and grow message history exactly like
+writes.
+
+Version 0.2 has cleanup indexes but no built-in pruning command. Budget message
+growth as:
+
+```text
+daily durable messages = daily actor writes + daily actor reads + daily callbacks
+```
+
+Review the [retention requirements](operations.md#retention-and-backups) before
+adopting a high-volume surface.
+
+## Measure the host application
+
+Run the adoption benchmark against a dedicated empty database with the same
+adapter and topology as production:
+
+```bash
+COUNT=25 \
+SOLID_OBJECTS_DATABASE_URL=mysql2://localhost/solid_objects_benchmark \
+bundle exec ruby -Ilib benchmark/adoption_latency.rb
+```
+
+It reports the first cold call, warm synchronous writes, ordered reads, and
+durable instance/message growth. Run it near the application process, with
+production-like TLS and network boundaries where applicable.
+
 The scripts and invocation examples are in the
 [development guide](development.md#benchmarks). PostgreSQL and MySQL should be
 benchmarked independently before selecting production capacity.

data/docs/development.md

@@ -66,12 +66,13 @@ correct change, rerun the focused test, then the complete database matrix.
 
 ## Benchmarks
 
-Scripts in `benchmark/` cover enqueue, claim, processing, cold actors, a hot
-actor, concurrent actors, synchronous latency, cache reuse, and query counts.
-Results describe one machine and database configuration; they are not universal
-capacity guarantees.
+Scripts in `benchmark/` cover adoption latency and durable row growth, enqueue,
+claim, processing, cold actors, a hot actor, concurrent actors, synchronous
+latency, cache reuse, and query counts. Results describe one machine and
+database configuration; they are not universal capacity guarantees.
 
 ```bash
+COUNT=25 bundle exec ruby -Ilib benchmark/adoption_latency.rb
 COUNT=500 bundle exec ruby -Ilib benchmark/enqueue.rb
 COUNT=500 bundle exec ruby -Ilib benchmark/claim.rb
 COUNT=500 bundle exec ruby -Ilib benchmark/processing.rb

data/docs/fit.md

@@ -0,0 +1,90 @@
+# Is Solid Objects a good fit?
+
+Solid Objects trades database work and retained message history for one strong
+property: all committed turns for one durable identity execute in order behind
+a fenced activation. Adopt it when that coordination property removes
+application-level locking, recovery, and scheduling code that would otherwise
+be difficult to make correct.
+
+## Strong fit signals
+
+Solid Objects is a good candidate when most of these are true:
+
+- State belongs to one durable identity such as a cart, room, device, session,
+  workflow, or user-specific schedule.
+- Writes for that identity must be serialized.
+- The state is naturally a bounded JSON document.
+- The object needs per-identity reminders, transactional external effects, or
+  reactive Rails views.
+- Different identities should run concurrently while one hot identity remains
+  deliberately sequential.
+- A durable mailbox and at-least-once retry are more valuable than minimum
+  request latency.
+- The application can operate and monitor additional database tables and, for
+  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.
+
+## Poor fit and anti-patterns
+
+Prefer ordinary Active Record, cache storage, Active Job, or an event pipeline
+when any of these dominate:
+
+- High-QPS request-path reads. Every actor attribute read is an ordered durable
+  message, not a direct `SELECT`, and retains a message-history row.
+- Hot counters such as abuse limits, impressions, page views, or metrics. One
+  identity is a serialization point and cannot gain throughput by adding
+  workers.
+- High-volume append workloads. Actor state rewrites a JSON document and the
+  mailbox retains one durable message per call.
+- Latency budgets where tens of milliseconds are already unacceptable.
+- Large, relational, or query-heavy state. Keep that data normalized in
+  application tables.
+- CPU-heavy work or slow network I/O inside a handler.
+- Cross-actor transactions or synchronous actor-to-actor call graphs.
+- 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.
+
+## Cost model
+
+Every synchronous or asynchronous invocation:
+
+- inserts one permanent `solid_objects_messages` row;
+- briefly occupies one ready or claimed membership row;
+- performs several short coordination transactions; and
+- may add effect, broadcast, or reminder records.
+
+The first call for an identity also inserts one `solid_objects_instances` row.
+Each application process that performs synchronous calls registers one caller
+process row. Actor state is rewritten as a JSON value on each successful
+mutation.
+
+There is no built-in retention command in 0.2. Completed message history grows
+until the host application implements a reviewed retention policy. See
+[performance measurements](benchmarks.md) and
+[retention guidance](operations.md#retention-and-backups).
+
+## Decision checklist
+
+Before adopting an actor, answer:
+
+1. What exact race or lifecycle problem requires serialized per-identity turns?
+2. What is the canonical actor identity?
+3. How hot can one identity become?
+4. Can the request path tolerate the measured cold and warm latency?
+5. How many calls and durable rows will this surface create per day?
+6. Which calls can be asynchronous?
+7. Which effects need downstream idempotency?
+8. Which runtime roles and operational alerts will the feature require?
+9. How will completed messages and outbox history be retained?
+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.

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:
@@ -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 synchronous
-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/roadmap.md

@@ -17,6 +17,8 @@
 - 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
@@ -50,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,6 +7,9 @@ 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 synchronous invocation path. Keep implementation

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/doctor.rb

@@ -0,0 +1,311 @@
+# rbs_inline: enabled
+
+require "solid_objects/mailbox"
+require "solid_objects/synchronous_invocation"
+
+module SolidObjects
+  class Doctor
+    class Check
+      # @rbs @name: Symbol
+      # @rbs @status: Symbol
+      # @rbs @message: String
+
+      attr_reader :name, :status, :message
+
+      # @rbs (name: Symbol, status: Symbol, message: String) -> void
+      def initialize(name:, status:, message:)
+        @name = name
+        @status = status
+        @message = message
+        freeze
+      end
+
+      # @rbs () -> bool
+      def failed?
+        status == :fail
+      end
+    end
+
+    class Report
+      # @rbs @checks: Array[Check]
+
+      attr_reader :checks
+
+      # @rbs (checks: Array[Check]) -> void
+      def initialize(checks:)
+        @checks = checks.freeze
+        freeze
+      end
+
+      # @rbs () -> bool
+      def healthy?
+        checks.none?(&:failed?)
+      end
+
+      # @rbs (Symbol) -> Check
+      def check(name)
+        checks.find { |candidate| candidate.name == name } ||
+          raise(KeyError, "unknown doctor check #{name.inspect}")
+      end
+
+      # @rbs () -> String
+      def to_s
+        lines = [ "Solid Objects doctor #{SolidObjects::VERSION}" ]
+        lines.concat(
+          checks.map do |check|
+            "#{check.status.to_s.upcase.ljust(4)} #{check.name}: #{check.message}"
+          end
+        )
+        lines.join("\n")
+      end
+    end
+
+    EXPECTED_COLUMNS = {
+      processes: %w[id kind hostname pid last_heartbeat_at shutdown_state],
+      instances: %w[
+        id actor_type actor_id state state_version next_message_sequence
+        activation_owner_id activation_token activation_expires_at
+        activation_generation
+      ],
+      messages: %w[
+        id instance_id message_kind arguments sequence attempt_count request_id
+        result error rejection completed_at rejected_at
+      ],
+      ready_messages: %w[id message_id instance_id sequence available_at],
+      claimed_messages: %w[
+        id message_id instance_id process_id activation_token
+        activation_generation claimed_at
+      ],
+      reminders: %w[id instance_id message_name next_run_at status],
+      effects: %w[id message_id instance_id effect_id status available_at],
+      broadcasts: %w[id message_id instance_id broadcast_id status available_at],
+      dead_letters: %w[id message_id instance_id actor_type actor_id attempts]
+    }.freeze
+
+    class ProbeActor < Actor
+      actor_type "solid_objects_doctor"
+
+      # @rbs (value: String) -> String
+      def ping(value:)
+        value
+      end
+    end
+
+    # @rbs @connection: untyped
+    # @rbs @configuration: Configuration
+
+    # @rbs (?connection: untyped, ?configuration: Configuration) -> void
+    def initialize(
+      connection: SolidObjects::Record.connection,
+      configuration: SolidObjects.configuration
+    )
+      @connection = connection
+      @configuration = configuration
+    end
+
+    # @rbs () -> Report
+    def call
+      configuration_check = check_configuration
+      schema_check = check_schema
+      checks = [
+        configuration_check,
+        schema_check,
+        check_authorization,
+        schema_check.failed? ? skipped_runtime : check_runtime,
+        ready_for_round_trip?(configuration_check, schema_check) ?
+          check_sync_round_trip :
+          skipped_round_trip
+      ]
+      Report.new(checks:)
+    end
+
+    private
+
+    attr_reader :connection, :configuration
+
+    # @rbs () -> Check
+    def check_configuration
+      configuration.validate!
+      pass(:configuration, "configuration is valid")
+    rescue => error
+      fail_check(:configuration, "#{error.class}: #{error.message}")
+    end
+
+    # @rbs () -> Check
+    def check_schema
+      missing_tables = expected_table_names - connection.data_sources
+      unless missing_tables.empty?
+        return fail_check(:schema, "missing tables: #{missing_tables.join(", ")}")
+      end
+
+      missing_columns = EXPECTED_COLUMNS.each_with_object([]) do |(name, expected), missing|
+        table_name = SolidObjects.table_name(name)
+        actual = connection.columns(table_name).map(&:name)
+        (expected - actual).each { |column| missing << "#{table_name}.#{column}" }
+      end
+      unless missing_columns.empty?
+        return fail_check(:schema, "missing columns: #{missing_columns.join(", ")}")
+      end
+
+      pass(:schema, "schema matches the #{SolidObjects::VERSION} runtime")
+    rescue => error
+      fail_check(:schema, "#{error.class}: #{error.message}")
+    end
+
+    # @rbs () -> Check
+    def check_authorization
+      outcomes = policy_probes.to_h do |name, arguments|
+        outcome = configuration.public_send(name).call(**arguments) ? :allow : :deny
+        [ name, outcome ]
+      rescue
+        [ name, :unknown ]
+      end
+      allowed = outcomes.select { |_, outcome| outcome == :allow }.keys
+      unknown = outcomes.select { |_, outcome| outcome == :unknown }.keys
+
+      if allowed.empty? && unknown.empty?
+        return warn_check(
+          :authorization,
+          "all five policies denied a neutral context; review the generated initializer before use"
+        )
+      end
+      risky = allowed & %i[
+        authorize_destroy
+        authorize_subscription
+        authorize_administration
+      ]
+      unless risky.empty?
+        return warn_check(
+          :authorization,
+          "sensitive policies allowed a neutral context: #{risky.join(", ")}"
+        )
+      end
+      unless unknown.empty?
+        return warn_check(
+          :authorization,
+          "#{allowed.length} of 5 policies allowed a neutral context; " \
+            "#{unknown.join(", ")} could not evaluate without application context"
+        )
+      end
+
+      pass(:authorization, "#{allowed.length} of 5 policies allowed a neutral context")
+    end
+
+    # @rbs () -> Check
+    def check_runtime
+      cutoff = SolidObjects.database_adapter.database_now -
+        configuration.process_alive_threshold
+      counts = Process
+        .where(shutdown_state: "running", last_heartbeat_at: cutoff..)
+        .group(:kind)
+        .count
+      if counts.empty?
+        return info(
+          :runtime,
+          "no live runtime roles; workerless synchronous calls are available, asynchronous features are not"
+        )
+      end
+
+      summary = counts.sort.map { |kind, count| "#{kind}=#{count}" }.join(", ")
+      pass(:runtime, "live runtime roles: #{summary}")
+    rescue => error
+      fail_check(:runtime, "#{error.class}: #{error.message}")
+    end
+
+    # @rbs () -> Check
+    def check_sync_round_trip
+      actor_id = SecureRandom.uuid
+      value = SecureRandom.hex(8)
+      process_registry = SolidObjects.caller_process.process_registry
+      reference = ProbeActor.ref(actor_id)
+      message_reference = Mailbox.new.enqueue(
+        reference,
+        :ping,
+        { value: },
+        kind: "sync"
+      )
+      result = SynchronousInvocation.new.call(message_reference, timeout: 5.seconds)
+      raise Error, "unexpected round-trip result" unless result == value
+
+      pass(:sync_round_trip, "durable synchronous actor call completed without a worker")
+    rescue => error
+      fail_check(:sync_round_trip, "#{error.class}: #{error.message}")
+    ensure
+      Instance.where(actor_type: ProbeActor.actor_type, actor_id:).delete_all if actor_id
+      process_registry&.stop
+      process_registry&.process_record&.delete
+    end
+
+    # @rbs (Check, Check) -> bool
+    def ready_for_round_trip?(configuration_check, schema_check)
+      !configuration_check.failed? && !schema_check.failed?
+    end
+
+    # @rbs () -> Check
+    def skipped_runtime
+      skip(:runtime, "schema check failed")
+    end
+
+    # @rbs () -> Check
+    def skipped_round_trip
+      skip(:sync_round_trip, "configuration or schema check failed")
+    end
+
+    # @rbs () -> Hash[Symbol, Hash[Symbol, untyped]]
+    def policy_probes
+      actor_arguments = {
+        actor_type: ProbeActor.actor_type,
+        actor_id: "doctor",
+        authorization_context: nil
+      }
+      {
+        authorize_message: actor_arguments.merge(
+          message_name: "ping",
+          arguments: { "value" => "doctor" }
+        ),
+        authorize_query: actor_arguments.merge(
+          message_name: "value",
+          arguments: {}
+        ),
+        authorize_destroy: actor_arguments,
+        authorize_subscription: actor_arguments,
+        authorize_administration: {
+          action: "doctor",
+          resource: "runtime",
+          resource_id: nil,
+          authorization_context: nil
+        }
+      }
+    end
+
+    # @rbs () -> Array[String]
+    def expected_table_names
+      EXPECTED_COLUMNS.keys.map { |name| SolidObjects.table_name(name) }
+    end
+
+    # @rbs (Symbol, String) -> Check
+    def pass(name, message)
+      Check.new(name:, status: :pass, message:)
+    end
+
+    # @rbs (Symbol, String) -> Check
+    def info(name, message)
+      Check.new(name:, status: :info, message:)
+    end
+
+    # @rbs (Symbol, String) -> Check
+    def warn_check(name, message)
+      Check.new(name:, status: :warn, message:)
+    end
+
+    # @rbs (Symbol, String) -> Check
+    def fail_check(name, message)
+      Check.new(name:, status: :fail, message:)
+    end
+
+    # @rbs (Symbol, String) -> Check
+    def skip(name, message)
+      Check.new(name:, status: :skip, message:)
+    end
+  end
+end

data/lib/solid_objects/version.rb

@@ -1,5 +1,5 @@
 # rbs_inline: enabled
 
 module SolidObjects
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/tasks/solid_objects_tasks.rake

@@ -0,0 +1,10 @@
+require "solid_objects/doctor"
+
+namespace :solid_objects do
+  desc "Verify the Solid Objects installation"
+  task doctor: :environment do
+    report = SolidObjects::Doctor.new.call
+    puts report
+    abort "Solid Objects doctor failed" unless report.healthy?
+  end
+end

data/sig/generated/lib/solid_objects/doctor.rbs

@@ -0,0 +1,111 @@
+# Generated from lib/solid_objects/doctor.rb with RBS::Inline
+
+module SolidObjects
+  class Doctor
+    class Check
+      @name: Symbol
+
+      @status: Symbol
+
+      @message: String
+
+      attr_reader name: untyped
+
+      attr_reader status: untyped
+
+      attr_reader message: untyped
+
+      # @rbs (name: Symbol, status: Symbol, message: String) -> void
+      def initialize: (name: Symbol, status: Symbol, message: String) -> void
+
+      # @rbs () -> bool
+      def failed?: () -> bool
+    end
+
+    class Report
+      @checks: Array[Check]
+
+      attr_reader checks: untyped
+
+      # @rbs (checks: Array[Check]) -> void
+      def initialize: (checks: Array[Check]) -> void
+
+      # @rbs () -> bool
+      def healthy?: () -> bool
+
+      # @rbs (Symbol) -> Check
+      def check: (Symbol) -> Check
+
+      # @rbs () -> String
+      def to_s: () -> String
+    end
+
+    EXPECTED_COLUMNS: untyped
+
+    class ProbeActor < Actor
+      # @rbs (value: String) -> String
+      def ping: (value: String) -> String
+    end
+
+    @configuration: Configuration
+
+    @connection: untyped
+
+    # @rbs (?connection: untyped, ?configuration: Configuration) -> void
+    def initialize: (?connection: untyped, ?configuration: Configuration) -> void
+
+    # @rbs () -> Report
+    def call: () -> Report
+
+    private
+
+    attr_reader connection: untyped
+
+    attr_reader configuration: untyped
+
+    # @rbs () -> Check
+    def check_configuration: () -> Check
+
+    # @rbs () -> Check
+    def check_schema: () -> Check
+
+    # @rbs () -> Check
+    def check_authorization: () -> Check
+
+    # @rbs () -> Check
+    def check_runtime: () -> Check
+
+    # @rbs () -> Check
+    def check_sync_round_trip: () -> Check
+
+    # @rbs (Check, Check) -> bool
+    def ready_for_round_trip?: (Check, Check) -> bool
+
+    # @rbs () -> Check
+    def skipped_runtime: () -> Check
+
+    # @rbs () -> Check
+    def skipped_round_trip: () -> Check
+
+    # @rbs () -> Hash[Symbol, Hash[Symbol, untyped]]
+    def policy_probes: () -> Hash[Symbol, Hash[Symbol, untyped]]
+
+    # @rbs () -> Array[String]
+    def expected_table_names: () -> Array[String]
+
+    # @rbs (Symbol, String) -> Check
+    def pass: (Symbol, String) -> Check
+
+    # @rbs (Symbol, String) -> Check
+    def info: (Symbol, String) -> Check
+
+    # @rbs (Symbol, String) -> Check
+    def warn_check: (Symbol, String) -> Check
+
+    # @rbs (Symbol, String) -> Check
+    def fail_check: (Symbol, String) -> Check
+
+    # @rbs (Symbol, String) -> Check
+    def skip: (Symbol, String) -> Check
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Lucas Carlson
@@ -278,6 +278,7 @@ files:
 - app/views/solid_objects/instances/index.html.erb
 - app/views/solid_objects/instances/show.html.erb
 - benchmark/activation_cache.rb
+- benchmark/adoption_latency.rb
 - benchmark/claim.rb
 - benchmark/cold_actors.rb
 - benchmark/concurrent_actors.rb
@@ -303,11 +304,14 @@ files:
 - docs/adr/0012-not-active-jobs.md
 - docs/adr/0013-database-adapters.md
 - docs/architecture.md
+- docs/authorization.md
 - docs/benchmarks.md
 - docs/correctness.md
 - docs/database-schema.md
 - docs/development.md
+- docs/fit.md
 - docs/implementation-plan.md
+- docs/migrating-existing-state.md
 - docs/operations.md
 - docs/realtime.md
 - docs/research/solid_queue.md
@@ -349,6 +353,7 @@ files:
 - lib/solid_objects/database_adapters/postgresql.rb
 - lib/solid_objects/database_adapters/sqlite.rb
 - lib/solid_objects/dead_letter_manager.rb
+- lib/solid_objects/doctor.rb
 - lib/solid_objects/dom_identity.rb
 - lib/solid_objects/effect_executor.rb
 - lib/solid_objects/effect_registry.rb
@@ -374,6 +379,7 @@ files:
 - lib/solid_objects/version.rb
 - lib/solid_objects/wake_up.rb
 - lib/solid_objects/worker.rb
+- lib/tasks/solid_objects_tasks.rake
 - sig/generated/controllers/solid_objects/application_controller.rbs
 - sig/generated/controllers/solid_objects/dead_letters_controller.rbs
 - sig/generated/controllers/solid_objects/instances_controller.rbs
@@ -400,6 +406,7 @@ files:
 - sig/generated/lib/solid_objects/database_adapters/postgresql.rbs
 - sig/generated/lib/solid_objects/database_adapters/sqlite.rbs
 - sig/generated/lib/solid_objects/dead_letter_manager.rbs
+- sig/generated/lib/solid_objects/doctor.rbs
 - sig/generated/lib/solid_objects/dom_identity.rbs
 - sig/generated/lib/solid_objects/effect_executor.rbs
 - sig/generated/lib/solid_objects/effect_registry.rbs