feat: add safe actor destruction

Authorize and linearize reference destruction on the actor instance row. Cascade actor-owned durable work, fence stale activations, and prevent claimed reminders from resurrecting a deleted incarnation. Cover deletion and in-flight races with deterministic Minitest integration tests.

Author: cardmagic

CHANGELOG.md

@@ -12,4 +12,6 @@
 - Add JSON actor state, versioned migrations, retries, and dead letters.
 - Add transactional effects, actor-to-actor messages, and durable reminders.
 - Add observable Turbo replacements through a durable broadcast outbox.
+- Add authorized, fenced actor destruction with cascading mailbox, reminder,
+  effect, broadcast, and dead-letter cleanup.
 - Support SQLite, PostgreSQL, and MySQL.

docs/architecture.md

@@ -2,7 +2,13 @@
 
 ## Purpose
 
-Solid Objects is a Rails engine that provides database-backed virtual actors for MySQL, PostgreSQL, and SQLite. A virtual actor is a logical object addressed by type and ID whose in-memory activation is created on demand, processes one mailbox turn at a time, persists JSON state, and can disappear when idle without losing its identity or state.
+Solid Objects ports the Cloudflare Durable Objects programming model to Rails.
+It is a database-backed virtual actor runtime for MySQL, PostgreSQL, and
+SQLite. A virtual actor is a logical object addressed by type and ID whose
+in-memory activation is created on demand, processes one mailbox turn at a
+time, persists JSON state, and can disappear when idle without losing its
+identity or state. This ports the programming model, not Cloudflare's
+serverless runtime, global placement, storage API, or platform guarantees.
 
 The runtime contract is:
 
@@ -53,11 +59,12 @@ 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`. Both paths authorize and enqueue through the client.
+delegate to `ask`. `destroy` is a reserved synchronous reference operation.
+All three paths authorize through the client.
 
 ### Client and mailbox
 
-The client finds or creates the actor instance and atomically allocates a sequence. It inserts one durable message-history row and one ready-membership row. It validates message names and JSON payloads before writing and enforces idempotency-key uniqueness, payload limits, and the per-actor mailbox cap. Distributed rate limiting and global admission control are not implemented.
+The client finds or creates the actor instance and atomically allocates a sequence. It inserts one durable message-history row and one ready-membership row. It validates message names and JSON payloads before writing and enforces idempotency-key uniqueness, payload limits, and the per-actor mailbox cap. It also authorizes and coordinates actor destruction. Distributed rate limiting and global admission control are not implemented.
 
 Message execution state is table membership, not a status column. The durable message remains for results, retention, and diagnostics. Only live work occupies `ready_messages` or `claimed_messages`, so completed history cannot inflate the polling index.
 
@@ -100,7 +107,11 @@ An effect worker claims due effect rows through the database coordination adapte
 
 ### Reminder scheduler
 
-The scheduler claims due reminder definitions, enqueues ordinary actor messages, and advances recurring reminders or completes one-shot reminders. A unique occurrence key prevents two schedulers from producing two mailbox rows for the same reminder occurrence.
+The scheduler claims due reminder definitions, locks the source actor instance,
+then enqueues the ordinary actor message and advances or completes the reminder
+in one transaction. A unique occurrence key prevents two schedulers from
+producing two mailbox rows for the same reminder occurrence. Locking the source
+instance first prevents a claimed reminder from recreating a destroyed actor.
 
 ### Broadcast worker
 
@@ -141,9 +152,9 @@ updates; it is not independently persisted.
 Lifecycle hooks are deterministic local hooks:
 
 - `on_activate` runs after state load and migration. State changes made there are included with the next successful message commit, not persisted on activation alone.
-- `on_deactivate` runs only on graceful local deactivation. Its state changes are not persisted and it must not be used for durable work.
+- `on_deactivate` runs only on graceful local deactivation. Its state changes are not persisted and it must not be used for durable work. Explicit destruction does not run lifecycle hooks.
 
-Durable cleanup belongs in messages, reminders, or effects.
+Durable application cleanup belongs in messages, reminders, or effects.
 
 ## Enqueue and sequence allocation
 
@@ -164,6 +175,37 @@ The increment and insert roll back together. The unique index on `(actor_type, a
 
 Committed concurrent enqueues have one database-defined sequence order. No order is promised between transactions that have not committed.
 
+## Actor destruction
+
+`ActorClass.ref(actor_id).destroy` is a synchronous, idempotent runtime
+operation. It is forbidden from actor context and has a separate
+`authorize_destroy` policy that runs before actor existence is revealed.
+
+Destruction uses one transaction:
+
+1. Resolve the actor type through the registry.
+2. Authorize the actor type and ID.
+3. Lock the actor instance by logical identity.
+4. Return `false` if it does not exist.
+5. Delete the instance.
+6. Let foreign-key cascades delete message history, ready and claimed
+   memberships, dead letters, reminders, effects, and broadcasts.
+7. Commit, emit `solid_objects.actor.destroyed`, and wake local waiters.
+
+The instance primary key is the actor-incarnation boundary. A worker holding an
+old lease can continue running Ruby code, but its fenced transaction cannot
+find the deleted instance and raises `LostActivation`. If the same logical
+identity is referenced later, enqueue creates a new instance with default
+state, state version, sequence 1, and a new primary key. An enqueue that loses
+the instance between lookup and locking retries against the new incarnation.
+
+A claimed reminder locks the source instance before enqueueing its occurrence,
+so it either commits before destruction and is deleted by the cascade, or
+observes the missing instance and does nothing. An already-running external
+effect, actor-to-actor delivery, or broadcast may have crossed the database
+boundary before destruction; it cannot be recalled. Its completion sees the
+deleted outbox row and cannot enqueue a callback or recreate the source actor.
+
 ## Candidate selection and fairness
 
 An actor is eligible when:
@@ -324,7 +366,10 @@ A reminder record contains actor identity, a reminder name, target message, JSON
 schedule :expire, at: 30.minutes.from_now, arguments: {}
 ```
 
-When due, the scheduler creates a normal mailbox row with an idempotency key derived from reminder ID and occurrence. The mailbox provides sequential processing and ordinary retry behavior.
+When due, the scheduler locks the source instance and creates a normal mailbox
+row with an idempotency key derived from reminder ID and occurrence. The
+mailbox insert and reminder advancement commit atomically. The mailbox provides
+sequential processing and ordinary retry behavior.
 
 Solid Objects persists each occurrence by its mailbox row. Unlike Orleans reminders, an outage does not intentionally discard a due occurrence. Recurring catch-up is configurable:
 
@@ -373,14 +418,18 @@ Each channel subscription transmits current observable replacements before strea
 
 ## Authorization
 
-Configuration provides four explicit policies:
+Configuration provides five explicit policies:
 
 - `authorize_message`
 - `authorize_query`
+- `authorize_destroy`
 - `authorize_subscription`
 - `authorize_administration`
 
-Each receives a request context, registered actor class, actor ID, and operation details. A host can set request context using an isolated execution-state carrier. Internal runtime deliveries carry a system context that is separately recognizable.
+Each receives a request context, actor type, actor ID, and relevant operation
+details. A host can set request context using an isolated execution-state
+carrier. Internal runtime deliveries carry a system context that is separately
+recognizable.
 
 No controller, channel, or administrative command treats an actor ID, message ID, request ID, or signed stream name as authorization.
 
@@ -515,7 +564,8 @@ PostgreSQL transaction-level advisory locks may be used for optional singleton m
 | Successful message commit | Fenced state, durable message result, claimed-membership deletion, effects, reminders, actor outbox, broadcasts |
 | Failed message attempt | Conditional error, claimed deletion, ready reinsertion or dead letter |
 | Renew or release lease | Conditional instance update |
-| Deliver reminder occurrence | Mailbox enqueue is one transaction; reminder advance is a second claim-checked transaction, bridged by a stable occurrence idempotency key |
+| Destroy actor | Instance identity lock and cascading delete of state, mailbox, reminders, and outboxes |
+| Deliver reminder occurrence | Source instance lock, mailbox enqueue, and reminder advance, with a stable occurrence idempotency key |
 | Claim outbox batch | Backend claim transaction and delivery ownership |
 | Record outbox outcome | Success or retry/dead status |
 

docs/correctness.md

@@ -32,6 +32,35 @@ finalization locks the instance and checks:
 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 |
@@ -71,7 +100,9 @@ The following are atomic:
 - 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.
+- 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.
 
@@ -80,6 +111,8 @@ Actor Ruby code and external I/O are never inside the actor-state transaction.
 `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
 

docs/database-schema.md

@@ -11,6 +11,11 @@ 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;
@@ -96,3 +101,11 @@ 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.

docs/operations.md

@@ -76,6 +76,24 @@ is evidence that alarms are being lost.
 
 Never bulk-update actor state. That bypasses lease ownership and fencing.
 
+## Actor destruction
+
+Delete an actor only through its authorized reference:
+
+```ruby
+Counter.ref("global").destroy(authorization_context: Current.user)
+```
+
+Do not delete `solid_objects_instances` directly. The public operation locks
+the identity, invalidates stale activations through the deleted incarnation
+key, cascades through all actor-owned rows, emits
+`solid_objects.actor.destroyed`, and wakes local waiters.
+
+Destruction removes pending outboxes but cannot recall external I/O,
+actor-to-actor delivery, or a broadcast that already started. Confirm
+downstream idempotency and application retention requirements before deleting
+an actor. Reusing the same actor type and ID creates a fresh incarnation.
+
 ## Monitoring
 
 Alert on:
@@ -86,6 +104,7 @@ Alert on:
 - actor turn duration and failures;
 - lost-activation rate;
 - dead-letter creation;
+- actor destruction rate;
 - stale process heartbeats;
 - effect and broadcast retry/dead counts;
 - due-reminder lag;

docs/security.md

@@ -3,14 +3,16 @@
 ## Policy hooks
 
 Solid Objects has separate hooks for sending messages, querying state,
-subscribing to actor streams, and administration. The host application supplies
-the authenticated request or connection as `authorization_context`.
-All four hooks deny by default.
+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.
 
 Method-style reference calls do not bypass these hooks. Public instance methods
 declared on an actor are part of its remotely addressable message surface and
 delegate to the authorized `tell` path. Keep implementation helpers private or
 protected. Query and attribute methods delegate to the authorized `ask` path.
+`reference.destroy` delegates to `authorize_destroy` before checking whether
+the actor exists, so denial does not reveal actor existence.
 
 Internal runtime delivery bypasses the public client only for rows already
 created by a committed actor turn. It never converts a database actor type into
@@ -47,6 +49,10 @@ host authentication and audit their use.
 Instrumentation excludes arguments, state, results, and effect payloads by
 default. Review custom logging and effect handlers for accidental disclosure.
 
+Actor destruction is not an administrative shortcut. Authorize tenancy and
+ownership explicitly in `authorize_destroy`; knowledge of an actor ID is never
+permission to delete its state or queued work.
+
 ## Denial of service
 
 Configure mailbox and byte limits. Add host rate limiting before public actor

lib/generators/solid_objects/templates/solid_objects.rb

@@ -7,6 +7,7 @@
   configuration.reminder_scheduler_count = 1
   configuration.authorize_message = ->(**) { false }
   configuration.authorize_query = ->(**) { false }
+  configuration.authorize_destroy = ->(**) { false }
   configuration.authorize_subscription = ->(**) { false }
   configuration.authorize_administration = ->(**) { false }
 end

lib/solid_objects/client.rb

@@ -59,6 +59,35 @@ def ask(reference, message_name, arguments, timeout:, idempotency_key: nil, auth
       wait_for_result(message_reference, timeout:)
     end
 
+    # @rbs (Reference, ?authorization_context: untyped) -> bool
+    def destroy(reference, authorization_context: nil)
+      raise ActorCallCycle, "actors cannot synchronously destroy another actor" if Context.current_actor
+
+      SolidObjects.registry.fetch(reference.actor_type)
+      authorize_destroy!(reference, authorization_context:)
+      instance_id = SolidObjects.database_adapter.transaction do
+        instance = Instance.lock.find_by(
+          actor_type: reference.actor_type,
+          actor_id: reference.actor_id
+        )
+        next unless instance
+
+        instance_id = instance.id
+        instance.delete
+        instance_id
+      end
+      return false unless instance_id
+
+      SolidObjects.instrument(
+        :"actor.destroyed",
+        instance_id:,
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id
+      )
+      SolidObjects.wake_up.signal
+      true
+    end
+
     private
 
     attr_reader :mailbox
@@ -77,6 +106,18 @@ def authorize!(hook, reference, message_name, arguments, authorization_context:)
       raise Unauthorized, "actor invocation is not authorized"
     end
 
+    # @rbs (Reference, authorization_context: untyped) -> void
+    def authorize_destroy!(reference, authorization_context:)
+      authorized = SolidObjects.configuration.authorize_destroy.call(
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        authorization_context:
+      )
+      return if authorized
+
+      raise Unauthorized, "actor destruction is not authorized"
+    end
+
     # @rbs (MessageReference, timeout: Numeric) -> untyped
     def wait_for_result(message_reference, timeout:)
       deadline = monotonic_now + timeout.to_f
@@ -100,6 +141,8 @@ def wait_for_result(message_reference, timeout:)
           timeout: [ remaining, SolidObjects.configuration.ask_polling_interval ].min
         )
       end
+    rescue ActiveRecord::RecordNotFound
+      raise ActorDestroyed, "actor was destroyed while waiting for its result"
     end
 
     # @rbs () -> Float

lib/solid_objects/configuration.rb

@@ -31,6 +31,7 @@ class Configuration
     # @rbs @wake_up_adapter: untyped
     # @rbs @authorize_message: Proc
     # @rbs @authorize_query: Proc
+    # @rbs @authorize_destroy: Proc
     # @rbs @authorize_subscription: Proc
     # @rbs @authorize_administration: Proc
 
@@ -63,6 +64,7 @@ class Configuration
       :wake_up_adapter,
       :authorize_message,
       :authorize_query,
+      :authorize_destroy,
       :authorize_subscription,
       :authorize_administration
 
@@ -101,6 +103,7 @@ def initialize
       end
       @authorize_message = ->(**) { false }
       @authorize_query = ->(**) { false }
+      @authorize_destroy = ->(**) { false }
       @authorize_subscription = ->(**) { false }
       @authorize_administration = ->(**) { false }
     end

lib/solid_objects/errors.rb

@@ -37,6 +37,9 @@ class InvalidStreamToken < Error
   class LostActivation < Error
   end
 
+  class ActorDestroyed < LostActivation
+  end
+
   class AskTimeout < Error
   end