solid_objects 0.1.0

data/docs/adr/0004-activation-leasing.md

@@ -0,0 +1,21 @@
+# ADR 0004: Renewable Database Activation Leases
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+One worker must process one actor at a time without holding a database connection for the actor's in-memory lifetime.
+
+## Decision
+
+The actor instance row stores an activation owner, expiration, and generation. PostgreSQL and MySQL workers select an available or expired actor with `FOR UPDATE SKIP LOCKED`. SQLite workers serialize the short claim transaction with `BEGIN IMMEDIATE`. Every strategy changes the owner, advances the generation, and sets a database-time expiration before commit.
+
+Lease renewal is a conditional update matching instance, owner, and generation. Graceful release uses the same predicate. Actor execution never holds a database transaction or checked-out connection across application code.
+
+## Consequences
+
+- A paused process can lose an activation even if its process heartbeat remains current.
+- Clock comparison uses the backend database's current time.
+- Lease duration must exceed renewal interval and configuration validation enforces it.
+- Expiration enables crash recovery but does not by itself reject stale writes; fencing does.

data/docs/adr/0005-fencing-tokens.md

@@ -0,0 +1,25 @@
+# ADR 0005: Every State Commit Is Fenced
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+An expired lease alone permits a paused worker to resume after a replacement worker has changed state.
+
+## Decision
+
+Every activation acquisition monotonically increments `activation_generation`. State/message/outbox commit locks the instance and verifies:
+
+- activation owner equals the committing worker
+- activation generation equals the worker's token
+- activation expiration is still in the future
+- the message is owned by the same activation generation
+
+If any predicate fails, the transaction raises `SolidObjects::LostActivation` and no state, completion, result, effect, reminder, or broadcast is persisted.
+
+## Consequences
+
+- Fencing tokens, not wall-clock expiry alone, prevent stale state writes.
+- Generation overflow is practically unreachable with a signed 64-bit positive counter and is guarded by a check constraint.
+- Any future storage backend must implement an equivalent conditional commit.

data/docs/adr/0006-at-least-once-delivery.md

@@ -0,0 +1,24 @@
+# ADR 0006: At-Least-Once Mailbox Delivery
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+A worker can die before committing a message, after actor code ran, or after external code performed an irreversible effect. Exactly-once execution cannot be guaranteed by a database mailbox.
+
+## Decision
+
+Mailbox delivery is at least once. State mutation, message completion, result persistence, and outbox insertion are atomic. An interrupted message whose commit is absent becomes eligible after lease recovery and may execute again.
+
+Actor code receives message ID, request ID, attempt, enqueue time, and idempotency key. Documentation requires idempotency for effects outside the actor commit.
+
+Message handlers themselves can run more than once. Sequential execution means one valid activation runs one turn at a time; it does not mean a handler runs once. Handlers for transitions such as `launch`, `checkout`, or `submit` must inspect durable actor state and return safely when the transition already happened. External calls belong in an outbox and still require downstream idempotency.
+
+## Consequences
+
+- No exactly-once claim appears in the API or documentation.
+- Pure state transitions are safe because failed transactions roll back.
+- Application handlers need durable state guards for non-repeatable logical transitions.
+- External systems require idempotency keys or deduplication.
+- `ask` timing out does not cancel its durable message.

data/docs/adr/0007-transactional-outbox.md

@@ -0,0 +1,21 @@
+# ADR 0007: External Effects and Broadcasts Use Outboxes
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+Calling an external system or broadcasting before the actor transaction commits can create phantom effects. Calling it after commit without a durable record can lose effects.
+
+## Decision
+
+`emit` stages an effect. Successful message commit inserts the effect in the same database transaction as state and message completion. Observable changes likewise insert broadcast rows in that transaction. Separate workers claim and deliver outbox rows at least once.
+
+Effect handlers must accept a stable effect ID as their idempotency key. Optional success and failure messages are enqueued back to the actor after delivery outcome is durably recorded.
+
+## Consequences
+
+- Slow network I/O never runs inside the actor-state transaction.
+- Delivery may be duplicated after a worker crash.
+- Consumers and effect handlers must be idempotent.
+- Outbox retention and replay are operational concerns.

data/docs/adr/0008-actor-communication.md

@@ -0,0 +1,21 @@
+# ADR 0008: Actor Communication Is Asynchronous
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+If actor A synchronously waits for actor B while B waits for A, sequential actors deadlock. Waiting also extends activation occupation and database pressure.
+
+## Decision
+
+Actor references support durable asynchronous `tell`. `ask` is a caller-facing request/response operation and must not be called from actor code. Actor code uses staged actor messages or request/result message pairs.
+
+Messages staged during actor execution are delivered through a transactional outbox so they exist if and only if the source message commits.
+
+## Consequences
+
+- Cyclic synchronous actor calls are rejected in actor context.
+- Workflows spanning actors are explicit state machines or sagas.
+- Cross-actor message order is not globally defined.
+- Each target actor allocates its own mailbox sequence at delivery time.

data/docs/adr/0009-realtime-updates.md

@@ -0,0 +1,21 @@
+# ADR 0009: Realtime Updates Use a Durable Broadcast Outbox
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+Action Cable broadcasts are online-only. A transaction can roll back, a broadcast process can crash, and a client can disconnect.
+
+## Decision
+
+The executor evaluates declared observables before and after a successful message. Changed values create broadcast outbox records inside the message commit. A broadcast worker delivers Turbo Stream replacements after commit.
+
+One `solid_object` block creates one signed Action Cable subscription and contains stable targets for multiple observables and components. Subscription authorization runs after token verification and before streaming. Reconnect refresh reads current actor state; the broadcast stream is an optimization, not state.
+
+## Consequences
+
+- Disconnected clients may miss individual broadcasts but can converge by refresh.
+- Broadcast delivery is at least once and replacements must be idempotent.
+- Actor IDs and signed stream names are identifiers, not authorization.
+- Realtime support is optional and loaded only when Action Cable and Turbo are present.

data/docs/adr/0010-state-versioning.md

@@ -0,0 +1,29 @@
+# ADR 0010: Explicit Actor State Versions
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+Persistent actors can outlive application releases. During a rolling deployment, old and new worker processes can briefly execute different actor code.
+
+## Decision
+
+Every actor class declares a current integer state version. Migrations must form an unbroken, one-step chain from stored version to current version. The runtime must refuse to activate an actor whose stored state version is newer than the actor class declares.
+
+Process metadata includes an application/runtime version. Deployments that change state shape must keep old code able to read the new representation or drain old workers before new-version messages can commit. Automatic downgrade is unsupported.
+
+Operating rules are normative:
+
+- Additive, backward-readable state changes do not require a version bump.
+- Destructive or reinterpretive changes use an expand/contract deployment across at least two releases.
+- A new migration may run only while every live worker can read the resulting representation, or after incompatible workers are drained.
+- Actor state migrations are permanent history. They cannot be squashed like Rails schema migrations because an actor may reactivate from a blob written years earlier.
+
+## Consequences
+
+- Rolling safety is an application responsibility and is never hidden.
+- Additive, backward-readable changes are preferred.
+- Destructive migrations require a coordinated drain or two-phase deployment.
+- Published migration steps remain in the actor code or an equivalent archival migration registry.
+- Migration errors fail the message without modifying stored state.

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

@@ -0,0 +1,34 @@
+# ADR 0011: Pluggable Wake-Up Strategy
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+Polling adds latency and database queries. PostgreSQL notifications are transactional but transient, session-scoped, coalesced in some cases, and subject to listener startup races. MySQL has no equivalent notification primitive. Some applications already operate Redis and may choose it as a low-latency accelerator, but Redis is not required infrastructure and cannot become durable truth.
+
+## 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.
+
+The interface supports:
+
+- Adaptive polling on every backend as the required fallback.
+- An in-process condition signal for same-process workers and waiters.
+- PostgreSQL `LISTEN/NOTIFY`.
+- Optional Redis Pub/Sub for applications that already operate Redis.
+
+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.
+
+## Consequences
+
+- Missing or duplicate notifications do not change correctness.
+- PostgreSQL listeners need one dedicated connection while active.
+- A reconnecting PostgreSQL listener must commit `LISTEN`, inspect current state, and then wait.
+- Redis loss only increases latency and never loses durable work.
+- Every adapter retains periodic polling to close startup, reconnect, and missed-message races.
+- Notification payloads never contain actor arguments or results.

data/docs/adr/0012-not-active-jobs.md

@@ -0,0 +1,21 @@
+# ADR 0012: Actor Messages Are Not Active Jobs
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+Active Job and Solid Queue provide durable independent jobs, but the actor contract couples an ordered mailbox, one logical activation, mutable state, fencing, request results, and transactional outboxes.
+
+## Decision
+
+Solid Objects implements its own mailbox and runtime rather than representing each actor message as an ordinary Active Job.
+
+Active Job may be used by host applications around Solid Objects, but it is not part of actor claiming, ordering, retries, state commit, effects, or reminders.
+
+## Consequences
+
+- Per-actor sequentiality is mandatory instead of opt-in concurrency control.
+- Message retry and serialization semantics are owned by Solid Objects.
+- State and message completion can be one database transaction.
+- The gem has more runtime code than an Active Job wrapper, but its guarantees are explicit and enforceable.

data/docs/adr/0013-database-adapters.md

@@ -0,0 +1,48 @@
+# ADR 0013: MySQL, PostgreSQL, and SQLite Backends
+
+- Status: Accepted
+- Date: 2026-08-05
+- Supersedes: ADR 0001
+
+## Context
+
+Solid Objects must work with the three databases Rails applications most commonly use without silently weakening mailbox ordering, activation ownership, or fencing.
+
+The databases expose different coordination features:
+
+- PostgreSQL and MySQL InnoDB support row locks and `FOR UPDATE SKIP LOCKED`.
+- SQLite has no row-level `SKIP LOCKED`, permits one writer at a time, and supports `BEGIN IMMEDIATE`.
+- PostgreSQL has JSONB, MySQL has JSON, and SQLite exposes Rails JSON serialization over its dynamic storage types.
+
+## Decision
+
+Solid Objects supports:
+
+- PostgreSQL 14 or newer
+- MySQL 8.0 or newer using InnoDB
+- SQLite 3.35 or newer
+
+A database adapter capability object owns:
+
+- Non-blocking claim strategy
+- Database current-time expression
+- JSON column migration type
+
+Explicit lock/deadlock/busy retry classification remains a hardening milestone.
+
+PostgreSQL and MySQL use bounded `FOR UPDATE SKIP LOCKED` claims in short transactions.
+
+SQLite uses the immediate write transactions provided by Rails 8 for coordination writes. Its single writer serializes candidate selection and claim. SQLite is correct for the tested contract but intended for development and modest single-host workloads because write concurrency is database-wide; explicit busy-error classification and retry are not yet implemented.
+
+All backends use the same conditional fenced commit predicate. Adapter differences may change throughput and lock granularity, never delivery semantics.
+
+Ready and claimed work live in narrow membership tables with ordinary composite indexes. Completed history never accumulates in the polling index, and no backend-specific partial index is required.
+
+## Consequences
+
+- The schema generator emits PostgreSQL JSONB, MySQL JSON, and SQLite JSON-compatible columns.
+- PostgreSQL, MySQL, and SQLite use the same ready- and claimed-membership tables.
+- MySQL tests require InnoDB and reject nontransactional table engines.
+- SQLite uses the adapter's configured busy timeout; WAL mode is an application operating choice.
+- Cross-backend integration tests exercise sequence allocation, claiming, lease renewal, fencing, atomic completion, and crash recovery.
+- PostgreSQL remains the benchmark and high-concurrency reference backend.