solid_objects 0.1.0 → 0.2.1

data/docs/adr/0011-wake-up-strategy.md

@@ -9,7 +9,8 @@ Polling adds latency and database queries. PostgreSQL notifications are transact
 
 ## Decision
 
-Database rows remain the only durable source of work and results. Wake-up adapters only tell workers and `ask` waiters to re-query those rows.
+Database rows remain the only durable source of work and results. Wake-up
+adapters only prompt workers and synchronous waiters to re-query those rows.
 
 The interface supports:
 
@@ -20,9 +21,17 @@ The interface supports:
 
 MySQL uses polling or optional Redis. SQLite uses polling plus the in-process signal; multi-host SQLite is outside its supported operating model.
 
-The coordination-overhead latency budget, measured from durable enqueue or completion commit until a waiting worker or caller begins its confirming query, is p99 at or below 100 milliseconds when a healthy cross-process wake-up adapter is enabled. Polling-only deployments accept up to the configured polling interval on each wait leg. End-to-end `ask` latency additionally includes queueing and actor execution and cannot have a library-wide bound.
-
-Polling-only `ask` is intended for background callers, scripts, and control paths. It is not recommended in latency-sensitive Rails request handlers. A request handler may use it only with an explicit timeout and an operationally verified wake-up adapter and actor latency budget.
+The synchronous caller first attempts to claim and execute the actor locally,
+so the normal path has no worker polling leg. When another process owns the
+activation, coordination overhead from completion commit until the caller's
+confirming query targets p99 at or below 100 milliseconds with a healthy
+cross-process wake-up adapter. Polling fallback accepts up to
+`sync_polling_interval` between observations. End-to-end latency still includes
+earlier mailbox work and actor execution and cannot have a library-wide bound.
+
+Direct methods and `sync` are intended for HTTP, MCP, scripts, and control
+paths whose handler and mailbox latency fit an explicit application budget.
+Timeout does not cancel durable work.
 
 ## Consequences
 

data/docs/architecture.md

@@ -58,9 +58,11 @@ The registry maps a stable persisted actor type string to a Ruby actor class. Re
 
 A reference contains actor type and normalized actor ID. It is cheap,
 serializable as data, and does not imply an active Ruby object. Declared
-message methods delegate to `tell`; declared query and attribute methods
-delegate to `ask`. `destroy` is a reserved synchronous reference operation.
-All three paths authorize through the client.
+message, query, and attribute methods use synchronous caller-assisted
+invocation. `sync` provides the same behavior for a dynamic operation name,
+while `async` only durably enqueues a message and returns its reference.
+`destroy` is a reserved synchronous reference operation. Every path authorizes
+through the client.
 
 ### Client and mailbox
 
@@ -73,10 +75,13 @@ Message execution state is table membership, not a status column. The durable me
 An activation lease is stored on the actor instance:
 
 - Owner process UUID
+- Unique activation token
 - Database-time expiration
 - Monotonic generation
 
-Acquisition and renewal are short database writes. Generation is the fencing token used by every state commit.
+Acquisition and renewal are short database writes. A fresh activation token
+distinguishes concurrent activations owned by the same process. Generation is
+the monotonic fencing token used by every state commit.
 
 ### Activation
 
@@ -140,9 +145,10 @@ end
 `attribute` creates actor instance readers and writers and an ordered read query.
 Public instance methods declared on the actor are messages. Declare helpers as
 private or protected. Messages and queries are exposed as methods on a
-reference: message methods delegate to `tell`, while query and attribute
-methods delegate to `ask`. Returned state snapshots are deeply frozen. The
-explicit `message` DSL remains available for dynamic definitions.
+reference through the same synchronous caller-assisted path. Returned state
+snapshots are deeply frozen. Use `async` for durable fire-and-forget delivery
+and `sync` for dynamic operation names. The explicit `message` DSL remains
+available for dynamic definitions.
 
 `message` and `query` both execute as durable mailbox turns. A query may not
 mutate state. The executor detects query mutation and fails the message. An
@@ -234,7 +240,7 @@ Before actor code:
 
 1. Renew if the lease would expire before the next renewal window.
 2. Load the earliest nonterminal mailbox sequence.
-3. Atomically move its ready membership to claimed membership for the current owner and generation and increment the durable attempt counter.
+3. Atomically move its ready membership to claimed membership for the current owner, activation token, and generation and increment the durable attempt counter.
 4. Set the actor's current message context.
 5. Snapshot state and observable values.
 
@@ -248,7 +254,7 @@ Actor code then executes with no open database transaction and no pinned connect
 
 It cannot:
 
-- Call `ask` from actor context
+- Call another actor directly or with `sync` from actor context
 - Perform a synchronous actor-to-actor wait
 - Assume execution happens once
 - Commit actor state directly
@@ -260,8 +266,8 @@ After actor code, the executor validates state and staged data as JSON and compu
 Successful completion uses one database transaction:
 
 1. Lock the instance row.
-2. Verify owner, generation, and an unexpired lease using database time.
-3. Lock the durable message and verify its claimed membership belongs to that owner and generation.
+2. Verify owner, activation token, generation, and an unexpired lease using database time.
+3. Lock the durable message and verify its claimed membership belongs to that owner, activation token, and generation.
 4. Update native JSON state and state version.
 5. Store the completion timestamp and result on the durable message and delete claimed membership.
 6. Insert staged effects.
@@ -319,21 +325,46 @@ The replacement has a higher generation. When the paused worker resumes, its con
 
 The effect can be delivered again. The stable effect ID is the idempotency key. This is why effect handlers must be idempotent.
 
-## Ask
+## Synchronous invocation
 
-`ask` durably enqueues a normal message with a request ID, then waits for the row to become completed, dead-lettered, or timed out. Every waiter re-queries durable rows. The implemented wake-up interface provides same-process signaling, bounded polling, and dependency injection. PostgreSQL `LISTEN/NOTIFY` and optional Redis Pub/Sub are planned adapters.
+A direct actor method or explicit `sync` call durably enqueues a normal mailbox
+message, then tries to claim that actor for the caller process. If successful,
+it drains earlier messages and the target through the same activation and
+executor used by workers. If another process owns the actor, the caller waits
+for the row to become completed, rejected, dead-lettered, destroyed, or timed
+out. Every wait re-queries durable rows. The implemented wake-up interface
+provides same-process signaling, bounded polling, and dependency injection.
+PostgreSQL `LISTEN/NOTIFY` and optional Redis Pub/Sub are planned adapters.
 
-With a healthy cross-process wake-up adapter, the coordination-overhead target from enqueue or completion commit to the confirming query is p99 at or below 100 milliseconds. End-to-end latency also includes mailbox queueing and handler execution. Polling-only deployments can pay the configured interval on both the worker and result legs, so polling-only `ask` is for background callers, scripts, and control paths rather than latency-sensitive Rails request handlers.
+The normal path does not wait for a worker polling interval because the caller
+assists execution immediately. End-to-end latency still includes earlier
+mailbox work, handler execution, and database commits. When another process
+owns the actor, a healthy cross-process wake-up adapter targets p99 coordination
+overhead at or below 100 milliseconds; polling fallback can pay up to
+`sync_polling_interval` between observations.
 
 Caller timeout:
 
-- Raises `SolidObjects::AskTimeout`.
+- Raises `SolidObjects::SyncTimeout`.
 - Does not cancel or delete the message.
 - Does not prevent later execution.
 - Leaves the result available until retention cleanup.
 
 The durable row remains after timeout and can be inspected directly by message ID. A public request-ID lookup and bounded retention commands are not yet implemented.
 
+`async` performs the same durable enqueue without caller assistance or result
+waiting and immediately returns a `MessageReference`. Runtime workers process
+it normally.
+
+## Domain rejection
+
+Actor code can call `reject` for a validation or business-rule outcome that
+must not retry. The executor restores pre-turn state, discards staged intents,
+stores the structured rejection, completes the claimed membership, and
+continues with the next sequence in one fenced transaction. Synchronous callers
+receive `SolidObjects::Rejected`. A rejection is neither an exception retry nor
+a dead letter.
+
 ## Effects and actor-to-actor delivery
 
 `emit` creates a staged effect:
@@ -380,7 +411,7 @@ Solid Objects persists each occurrence by its mailbox row. Unlike Orleans remind
 
 Durable reminders are alarms, and an alarm can be lost at the application level even while the database and actor state remain healthy. A reminder callback may dead-letter, a handler may fail to schedule its successor, or a signup/configuration path may never enqueue the first message. Unlike a periodic full sweep, a self-scheduling actor can then remain silently inert forever.
 
-Applications with self-scheduling actors should run a lower-frequency reconciliation job. The reconciler may read actor state and report drift, but it never writes actor state directly. Every repair is a normal authorized `tell`, so the actor decides whether the transition is still necessary and all ordering, lease, fencing, and audit rules remain intact.
+Applications with self-scheduling actors should run a lower-frequency reconciliation job. The reconciler may read actor state and report drift, but it never writes actor state directly. Every repair is a normal authorized `async` invocation, so the actor decides whether the transition is still necessary and all ordering, lease, fencing, and audit rules remain intact.
 
 `SolidObjects::Instance` exposes batchable read relations:
 
@@ -392,7 +423,7 @@ The expected drift categories are actors with a lost alarm, missing actors for l
 
 Bulk repair updates to `solid_objects_instances` are forbidden. They bypass activation ownership and fencing and can overwrite a concurrently committed actor state. Direct reads are observational; writes go through actor messages.
 
-Large repairs use `tell(..., available_at:)` to spread work over an application-defined dispatch window. The durable message records the requested availability and ready membership drives the hot polling query. This prevents reconciliation from flooding mailboxes and starving normal traffic.
+Large repairs use `async(..., available_at:)` to spread work over an application-defined dispatch window. The durable message records the requested availability and ready membership drives the hot polling query. This prevents reconciliation from flooding mailboxes and starving normal traffic.
 
 ## Realtime integration
 
@@ -589,8 +620,8 @@ All backends use unique identity and sequence constraints, short transactions, a
 ## Answers to required correctness questions
 
 1. **How is a per-actor sequence allocated safely?** The instance row is created uniquely, locked in the enqueue transaction, incremented, and the message inserted under a unique actor/sequence index.
-2. **How is one valid activation guaranteed?** Claim atomically changes owner and increments generation on one locked instance row. Only the matching unexpired owner/generation can commit.
-3. **How are stale writes rejected?** Every commit verifies owner, generation, and database-time expiration.
+2. **How is one valid activation guaranteed?** Claim atomically changes owner, creates a unique activation token, and increments generation on one locked instance row. Only the matching unexpired owner/token/generation can commit.
+3. **How are stale writes rejected?** Every commit verifies owner, activation token, generation, and database-time expiration.
 4. **What if a worker dies during execution?** No actor transaction remains open. After lease expiry, a new generation retries the uncommitted message.
 5. **What if it dies after commit but before acknowledgement?** Completion and state are already durable, so the new activation skips that message.
 6. **How are external effects retry-safe?** Effects are inserted atomically into an outbox and use a stable effect ID for handler idempotency.
@@ -601,7 +632,7 @@ All backends use unique identity and sequence constraints, short transactions, a
 11. **How are actors deactivated?** Idle cache timeout or eviction, best-effort hook, conditional lease release.
 12. **How are leases renewed?** Conditional database update by instance, owner, generation, and unexpired lease.
 13. **How does graceful shutdown work?** Stop claims, finish current turn within timeout, release cached leases, stop heartbeat, mark process stopped.
-14. **How does ask work across processes?** A wake-up adapter prompts a durable result query; periodic polling remains the fallback. Polling-only use is scoped to non-latency-sensitive callers.
+14. **How does synchronous invocation work across processes?** The caller first tries to claim and execute the actor locally. If another process owns it, a wake-up adapter prompts a durable result query and bounded polling remains the fallback.
 15. **What happens after caller timeout?** The durable message continues and its eventual result remains on the message row.
 16. **How are results cleaned up?** The schema has cleanup indexes, but bounded retention tooling is not implemented yet.
 17. **How are large mailboxes managed?** The implemented controls are the per-actor mailbox cap, payload caps, and fair activation yields; rate and global admission controls remain roadmap work.

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,25 +1,95 @@
-# 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.
 
-Measured 2026-08-05 on an Apple M5 with 24 GB RAM, Ruby 4.0.5, Rails 8.1.3.1,
+## 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.
 
 | Scenario | Result |
 | --- | ---: |
-| Enqueue, one actor | 522.4 messages/s |
-| Claim, 200 actors | 1,009.3 claims/s |
-| Process, 40 actors round-robin | 548.7 messages/s |
-| Process, 200 cold actors | 119.5 messages/s |
-| Process, one hot actor | 729.1 messages/s |
-| Process, four workers | 568.2 messages/s |
-| Ask latency | p50 9.2 ms, p95 15.6 ms, p99 53.7 ms |
+| Enqueue, one actor | 629.2 messages/s |
+| Claim, 200 actors | 1,038.4 claims/s |
+| Process, 40 actors round-robin | 548.1 messages/s |
+| Process, 200 cold actors | 121.5 messages/s |
+| Process, one hot actor | 726.4 messages/s |
+| Process, four workers | 556.5 messages/s |
+| Synchronous latency | p50 1.8 ms, p95 25.6 ms, p99 156.2 ms |
 | Activation reuse | 98.0%, four activations for 200 messages |
-| Queries for one message turn | 28 |
+| 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

data/docs/correctness.md

@@ -20,11 +20,14 @@ messages until success or dead-lettering.
 
 ## Ownership and fencing
 
-Claiming an actor writes a process UUID, database-time expiration, and a
-monotonically increasing generation. Every successful or failed message
-finalization locks the instance and checks:
+Claiming an actor writes a process UUID, a unique activation token,
+database-time expiration, and a monotonically increasing generation. The token
+separates concurrent activations in one process; the generation fences every
+older activation. Every successful or failed message finalization locks the
+instance and checks:
 
 - owner UUID matches;
+- activation token matches;
 - generation matches;
 - expiration is still in the future according to database time; and
 - claimed-message membership names the same owner and generation.
@@ -106,13 +109,29 @@ The following are atomic:
 
 Actor Ruby code and external I/O are never inside the actor-state transaction.
 
-## Ask
+## Synchronous invocation
 
-`ask` is a durable message followed by result polling and wake-up hints. Timeout
-does not cancel the message. The current cross-process fallback is polling;
-therefore polling-only ask is not recommended in latency-sensitive HTTP paths.
-Destroying the actor while an `ask` is waiting removes its message, wakes the
-caller, and raises `SolidObjects::ActorDestroyed`.
+A direct reference method or explicit `sync` call durably enqueues an ordinary
+mailbox message. The caller then attempts to claim that actor and execute
+through the same activation, lease renewal, fencing, and executor code used by
+a worker. It drains earlier messages first and returns only the committed
+result. A worker may win the activation instead; the caller then observes the
+durable result through wake-up hints with bounded polling as fallback.
+
+Timeout raises `SolidObjects::SyncTimeout` but does not cancel the message.
+Destroying the actor while a synchronous caller waits removes its message,
+wakes the caller, and raises `SolidObjects::ActorDestroyed`.
+
+`async` performs only the durable enqueue and immediately returns a
+`MessageReference`.
+
+## Domain rejection
+
+`reject` is a terminal domain outcome, not an infrastructure failure. It rolls
+back in-memory state and staged intents, stores a structured rejection on the
+message, removes claimed membership, and lets the next sequence run. It is
+never retried or dead-lettered. The synchronous caller receives
+`SolidObjects::Rejected`; asynchronous callers can inspect the message status.
 
 ## Database dependencies
 

data/docs/database-schema.md

@@ -8,8 +8,9 @@ migrations load. No partial indexes are used.
 ### `instances`
 
 One row per `(actor_type, actor_id)`. Stores JSON state, state version,
-next-message sequence, activation owner/expiration/generation, pause state, and
-lifecycle timestamps.
+next-message sequence, activation owner/token/expiration/generation, pause
+state, and lifecycle timestamps. The owner/token pairing is constrained so one
+process row cannot make two concurrent activations appear identical.
 
 Deleting an instance is the actor-incarnation boundary. Foreign keys cascade
 the delete through messages, ready and claimed memberships, reminders, effects,
@@ -27,14 +28,17 @@ Indexes:
 
 Durable immutable invocation identity and arguments plus sequence, attempt
 count, request/idempotency IDs, result/error, requested availability, and
-execution timestamps. It intentionally has no status column.
+execution timestamps. A terminal domain rejection stores a structured
+code/message/details document and rejection time. The table intentionally has
+no status column.
 
 Indexes:
 
 - unique instance/sequence and actor identity/sequence: mailbox order;
-- unique request ID: ask lookup;
+- unique request ID: synchronous result lookup;
 - unique instance/idempotency key: deduplicated enqueue;
-- completion/ID: bounded retention cleanup.
+- completion/ID: bounded retention cleanup;
+- rejection/ID: bounded rejection inspection and cleanup.
 
 ### `ready_messages`
 
@@ -50,7 +54,8 @@ Indexes:
 ### `claimed_messages`
 
 Small hot membership table for one message currently owned by an activation.
-It records process UUID, activation generation, and claim time.
+It records process UUID, unique activation token, activation generation, and
+claim time.
 
 Indexes:
 
@@ -108,4 +113,7 @@ The public `reference.destroy` operation locks the instance row before deleting
 it. Every actor-owned table has a cascading foreign key either directly to the
 instance or through its message row. No application-side bulk delete can leave
 an executable orphan. Process registry rows are not actor-owned and remain
-available for worker lifecycle accounting.
+available for worker lifecycle accounting. Activation-owner foreign keys use
+restrictive deletion so the owner/token check remains enforceable on MySQL;
+runtime deregistration clears leases and claims before a process row can be
+pruned.

data/docs/development.md

@@ -66,19 +66,20 @@ 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, ask 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
 COUNT=500 bundle exec ruby -Ilib benchmark/cold_actors.rb
 COUNT=500 bundle exec ruby -Ilib benchmark/hot_actor.rb
 COUNT=500 CONCURRENCY=4 bundle exec ruby -Ilib benchmark/concurrent_actors.rb
-COUNT=100 bundle exec ruby -Ilib benchmark/ask_latency.rb
+COUNT=100 bundle exec ruby -Ilib benchmark/sync_latency.rb
 COUNT=500 bundle exec ruby -Ilib benchmark/activation_cache.rb
 bundle exec ruby -Ilib benchmark/query_count.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.