solid_objects 0.1.0

data/docs/correctness.md

@@ -0,0 +1,124 @@
+# Correctness and delivery semantics
+
+## Contract
+
+Messages for one actor are durably enqueued and processed sequentially, at
+least once, by at most one valid activation lease holder at a time. Different
+actor identities may execute concurrently.
+
+Exactly-once execution is not provided.
+
+## Ordering
+
+Enqueue locks the actor instance, allocates `next_message_sequence`, and inserts
+the durable message and ready membership in one transaction. Unique indexes on
+instance/sequence and actor identity/sequence enforce the final invariant.
+
+The activation always claims the lowest live sequence for its actor. A
+retryable failure returns that message to ready membership, so it blocks later
+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:
+
+- owner UUID matches;
+- generation matches;
+- expiration is still in the future according to database time; and
+- claimed-message membership names the same owner and generation.
+
+A stale worker can continue running Ruby code, but it cannot commit state,
+completion, or outboxes.
+
+## Destruction
+
+`reference.destroy` locks and deletes the actor instance in one transaction.
+Cascading foreign keys delete its message history, ready and claimed
+memberships, dead letters, reminders, effects, and broadcasts. The operation
+returns `true` when it deletes an incarnation and `false` when no incarnation
+exists.
+
+The deleted instance primary key is also the fencing boundary. An activation
+that was executing before destruction raises `LostActivation` when it attempts
+to commit because its instance no longer exists. Reusing the logical actor
+type and ID creates a fresh incarnation with a different primary key, default
+state, and sequence 1; an old lease cannot address or commit into it.
+
+An enqueue racing with destruction is ordered by the instance lock. Work that
+commits first is deleted; work that observes the deletion retries against a new
+incarnation. A claimed reminder cannot resurrect an old incarnation because
+reminder delivery locks the source instance and atomically advances the
+reminder with its mailbox insert.
+
+Destruction removes pending and claimed outbox records, but it cannot recall
+external I/O, actor-to-actor delivery, or a broadcast that began before the
+delete. A stale outbox completion cannot record success, enqueue an actor
+callback, or recreate the source actor. Applications must still make external
+effect handlers idempotent.
+
+Destruction is synchronous, forbidden from actor context, authorized by
+`authorize_destroy`, and does not run `on_deactivate`.
+
+## Crash matrix
+
+| Failure point | Durable outcome |
+| --- | --- |
+| Before message claim | Ready membership remains. |
+| After claim, before handler | Claimed membership is recovered after lease loss. |
+| During handler | In-memory work is lost and the message can run again. |
+| During fenced commit | The database commits every state/message/outbox write or none. |
+| After fenced commit | The message is complete; there is no separate acknowledgement to lose. |
+| During external effect | The stable effect ID is reused, but the provider call can repeat. |
+| During broadcast delivery | The durable row retries; reconnect refresh repairs client staleness. |
+
+## Handler idempotency
+
+Sequential does not mean once. A message such as `launch` still needs a durable
+guard:
+
+```ruby
+def launch
+  return if status == "launched"
+
+  self.status = "launched"
+  emit :launch_vehicle, launch_id: actor_id
+end
+```
+
+The guard prevents a repeated state transition. The effect consumer still
+deduplicates with `context.id`.
+
+## Atomic boundaries
+
+The following are atomic:
+
+- actor creation, sequence allocation, durable message, and ready membership;
+- activation owner, expiration, and generation acquisition;
+- ready-to-claimed membership move and attempt increment;
+- state, state version, message result/completion, claimed deletion, effects,
+  reminders, outbound actor messages, and observable broadcasts;
+- failed-attempt record plus ready reinsertion or dead letter;
+- effect completion plus its optional actor outcome message;
+- reminder occurrence enqueue plus reminder advancement; and
+- actor destruction plus cascading removal of all actor-owned rows.
+
+Actor Ruby code and external I/O are never inside the actor-state transaction.
+
+## Ask
+
+`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`.
+
+## Database dependencies
+
+PostgreSQL and MySQL use primary-key `FOR UPDATE SKIP LOCKED` attempts after a
+read-only grouped scan of the narrow membership tables. SQLite relies on Active
+Record's immediate write transactions and its one-writer serialization.
+
+All three rely on transactional tables, foreign keys, unique constraints,
+database time, and JSON-compatible columns. MySQL requires InnoDB.

data/docs/database-schema.md

@@ -0,0 +1,111 @@
+# Database schema
+
+The default prefix is `solid_objects_`. It is configurable before models and
+migrations load. No partial indexes are used.
+
+## Tables
+
+### `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.
+
+Deleting an instance is the actor-incarnation boundary. Foreign keys cascade
+the delete through messages, ready and claimed memberships, reminders, effects,
+broadcasts, and dead letters. Reusing the logical identity creates a new
+instance primary key with fresh state and message sequence.
+
+Indexes:
+
+- unique identity: enforces one logical actor;
+- lease expiration/last claim/ID: operational lease scans and cleanup;
+- owner: dead-process cleanup;
+- last used/ID: retention and reconciliation.
+
+### `messages`
+
+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.
+
+Indexes:
+
+- unique instance/sequence and actor identity/sequence: mailbox order;
+- unique request ID: ask lookup;
+- unique instance/idempotency key: deduplicated enqueue;
+- completion/ID: bounded retention cleanup.
+
+### `ready_messages`
+
+Small hot membership table for due or future work. A row exists only while its
+message is ready.
+
+Indexes:
+
+- unique message ID;
+- unique instance/sequence;
+- availability/instance/sequence polling index.
+
+### `claimed_messages`
+
+Small hot membership table for one message currently owned by an activation.
+It records process UUID, activation generation, and claim time.
+
+Indexes:
+
+- unique message ID;
+- unique instance ID, enforcing at most one claimed turn for an actor;
+- process/claim time for crash cleanup.
+
+### `reminders`
+
+Durable one-shot or recurring alarm definitions. Unique instance/name makes
+rescheduling an actor-owned reminder deterministic. Status/next-run/ID drives
+the due scan. Claim ownership references the process registry, and constraints
+limit recurrence intervals, missed-work policies, and statuses.
+
+### `effects`
+
+Transactional external-effect outbox. It stores stable effect UUID, arguments,
+optional actor outcome messages, attempts, claim ownership, result/error, and
+completion time. Claim ownership references the process registry.
+Status/availability/ID drives delivery; completion/ID drives cleanup.
+
+### `broadcasts`
+
+Durable observable-change outbox. The unique message/observable key prevents
+duplicate rows for one actor turn. Claim and delivery indexes support retries
+and cleanup.
+
+### `dead_letters`
+
+Permanent message failures with original identity/arguments, attempts,
+exception summary, bounded backtrace, failure times, and optional retried
+message ID.
+
+### `processes`
+
+Worker/effect/reminder/broadcast process UUID, kind, hostname, PID, start and
+heartbeat times, metadata, graceful shutdown state, and stop times.
+
+## JSON types
+
+PostgreSQL uses JSONB. MySQL uses native JSON. SQLite uses Active Record's JSON
+type. Ruby `Marshal` is never used.
+
+## Why membership tables
+
+Completed messages remain useful history, but they never occupy the polling
+index. Moving a message between ready and claimed tables makes executable state
+physical table membership. The hot indexes stay proportional to live work,
+avoid backend-specific partial indexes, and are portable across all supported
+databases.
+
+## Cascading destruction
+
+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.

data/docs/development.md

@@ -0,0 +1,87 @@
+# Development guide
+
+## Requirements
+
+- Ruby 3.3 or newer
+- Rails 8.0 or newer
+- SQLite 3.35+, PostgreSQL 14+, and MySQL 8.0/InnoDB for the full matrix
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+## Tests
+
+The suite uses Minitest and follows Solid Queue's broad structure: unit tests,
+model/schema tests, engine boot tests, and real database integration tests.
+Concurrency tests use queues and notification barriers instead of timing-only
+sleeps.
+
+```bash
+bundle exec rake test
+SOLID_OBJECTS_DATABASE_URL=postgresql://... bundle exec rake test
+SOLID_OBJECTS_DATABASE_URL=mysql2://... bundle exec rake test
+```
+
+Each database run must start from an empty dedicated test database because the
+test helper applies the engine migration.
+
+## Inline RBS
+
+Ruby source starts with:
+
+```ruby
+# rbs_inline: enabled
+```
+
+Methods and instance variables use `# @rbs` annotations. Generate and validate
+signatures with:
+
+```bash
+bundle exec rake rbs
+```
+
+This follows the inline convention used by `cardmagic/classifier`.
+
+## Formatting and security
+
+```bash
+bundle exec standardrb
+bundle exec rubocop
+bundle exec rake rbs steep
+bundle exec brakeman --force --no-pager -q .
+bundle exec rake
+```
+
+`.rubocop.yml` is pinned to the policy shape in Solid Queue main at commit
+`86f3d92f1dd68547ec0ebe960fc9933c203d9e51`: Rails Omakase, Ruby 3.3, and its
+schema/template exclusions. Rails Omakase is canonical where the policies
+conflict. Standard remains an additional gate with only its opposing
+array/hash-bracket whitespace cops ignored.
+
+Run a failing Minitest first for behavioral changes, implement the smallest
+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.
+
+```bash
+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=500 bundle exec ruby -Ilib benchmark/activation_cache.rb
+bundle exec ruby -Ilib benchmark/query_count.rb
+```
+
+SQLite is the default. Set `SOLID_OBJECTS_DATABASE_URL` to benchmark a dedicated
+empty PostgreSQL or MySQL database.