feat: cache idle activations

Author: cardmagic

CHANGELOG.md

@@ -42,6 +42,9 @@
 - Add MySQL 8.0+ through the optional `mysql2` driver with pooled transactions,
   an InnoDB schema, scoped enqueue deadlock recovery, diagnostics, and
   real-server coverage across MySQL 8.0 and 8.4.
+- Add hydrated idle activation reuse with renewable fenced leases, protected
+  async lifecycle hooks, state restoration after failed turns, and release on
+  timeout, fairness yield, lease loss, and shutdown.
 
 ## 0.1.0 - 2026-08-13
 

README.md

@@ -754,6 +754,8 @@ IDs and observable values are not authorization.
 - Different actor identities may execute concurrently.
 - A worker drains at most `maxMessagesPerActivationPass` turns from one actor,
   then yields its still-due work behind actors that were already waiting.
+- Long-running workers reuse hydrated actors for
+  `idleDeactivationTimeoutMilliseconds` while renewing the same fenced lease.
 - State, completion, staged messages, effects, reminders, commit actions, and
   observable broadcasts share one fenced commit.
 - A lost or expired activation lease cannot commit.
@@ -762,6 +764,11 @@ IDs and observable values are not authorization.
 - Effects can execute more than once.
 - Results and snapshots are deeply frozen copies.
 
+Override protected `onActivate()` and `onDeactivate()` methods when an actor
+needs a process-local resource during that window. Hooks may be asynchronous,
+cannot write through a guarded application database, and are nondurable;
+`onDeactivate()` is best effort and must not carry correctness work.
+
 ## Current scope
 
 The current runtime supports Node.js 24, SQLite through built-in `node:sqlite`,

docs/architecture.md

@@ -55,6 +55,15 @@ moves only that actor's already-due ready memberships to current database time.
 Actors with older ready work therefore win the next global claim; delayed work
 keeps its original future availability.
 
+When a pass becomes idle, a long-running worker keeps the hydrated actor and
+continues renewing the same fenced lease until its idle timeout. A later turn
+on that actor reuses both its persisted public fields and process-local private
+fields. Failed and rejected turns restore public fields to their pre-turn
+values before reuse. Fairness yield, timeout, lease loss, and shutdown run the
+best-effort deactivation hook and conditionally release the matching lease.
+One-shot drain helpers release immediately because they will not remain alive
+to renew.
+
 Realtime delivery is transport-neutral. A host-authenticated session authorizes
 actor subscriptions, replays a committed observable projection, and follows
 the durable broadcast outbox in revision order. The browser client applies the

docs/correctness.md

@@ -17,6 +17,10 @@
 - Activation passes are bounded. Yielding changes ready-membership polling
   order only; it neither changes durable message sequence nor makes future work
   due early.
+- Idle hydrated actors remain fenced by the same renewable lease. Cache reuse
+  never bypasses claim membership or the commit fence, failed turns restore
+  their public fields before reuse, and conditional release cannot clear a
+  newer owner or generation.
 - `guardApplicationDatabase()` rejects direct application writes during actor
   operations, observable and payload projections, and state migrations. It
   permits only `SELECT` through row-returning methods; commit actions remain the

docs/operations.md

@@ -21,6 +21,20 @@ when a few actor identities stay continuously busy; higher values reduce claim
 overhead for isolated backlogs. `solid_objects.activation.yielded` reports the
 actor identity, turns processed, and remaining due membership count.
 
+Workers retain a hydrated actor and its fenced lease for
+`idleDeactivationTimeoutMilliseconds`, which defaults to 30 seconds. Idle
+leases renew at `leaseRenewalIntervalMilliseconds`; the worker polling cadence
+is capped at that interval while any activation may be cached. Fairness yield,
+lease loss, timeout, and shutdown release the lease. `runUntilIdle()` and the
+runtime's synchronous caller release before returning because they are no
+longer polling.
+
+Actors can override protected `onActivate()` and `onDeactivate()` methods for
+nondurable, process-local resources. Either hook may be asynchronous. Hook code
+runs under the application-write guard, and `onDeactivate()` is best effort:
+it may not run after a crash, cannot establish a correctness guarantee, and a
+failure is logged without preventing lease release.
+
 `runtime.processes.all()` returns administration-authorized immutable process
 metadata with a current `stale` flag. `cleanup()` reauthorizes separately and
 atomically fences stale processes out of every owned role claim before waking

docs/parity.md

@@ -26,7 +26,7 @@ Reference: Ruby `solid_objects` 0.12.0 at commit `a01b6f5`.
 | Ordered mailbox, sequence allocation, idempotency, retries, dead letters, leases, renewal, and fenced commits | Native  | Relational ready/claimed membership tables, durable history, and adapter-appropriate sequence locking.                                                                                                     |
 | Domain rejection and strict poison ordering                                                                   | Native  | Rejections roll back without retry; retryable failures block later operations until completion or dead-lettering.                                                                                          |
 | Bounded activation passes and hot-actor fairness                                                              | Native  | Workers preferentially drain one actor to a configurable cap, then move only its already-due memberships behind actors already waiting.                                                                    |
-| Idle activation cache                                                                                         | Planned | Add short-lived hydrated actor reuse with lease renewal and pressure eviction without weakening fenced commits.                                                                                            |
+| Idle activation cache                                                                                         | Native  | Long-running workers retain hydrated actors under renewable fenced leases, restore public state after failed turns, and release on timeout, fairness yield, lease loss, or shutdown.                       |
 | Transactional effects and outcome operations                                                                  | Native  | At-least-once effect handlers with stable IDs and success/failure actor operations.                                                                                                                        |
 | Actor-to-actor delivery                                                                                       | Native  | `sendTo(reference).operation()` stages delivery in the source actor commit.                                                                                                                                |
 | One-shot and recurring reminders                                                                              | Native  | Scheduling, replacement events, catch-up policy, stale-claim recovery, pausing, authorized inspection, and idempotent resume are implemented.                                                              |

src/actor.ts

@@ -117,6 +117,18 @@ export abstract class Actor {
     return {}
   }
 
+  async activate(): Promise<void> {
+    await this.onActivate()
+  }
+
+  async deactivate(): Promise<void> {
+    await this.onDeactivate()
+  }
+
+  protected onActivate(): void | Promise<void> {}
+
+  protected onDeactivate(): void | Promise<void> {}
+
   reject(code: string, options: { message: string; details?: Record<string, unknown> }): never {
     if (!/^[a-z][a-z0-9_]*$/.test(code)) {
       throw new TypeError("rejection code must contain lowercase letters, digits, and underscores")

src/configuration.ts

@@ -43,6 +43,7 @@ export interface SolidObjectsConfiguration {
   syncPollingIntervalMilliseconds?: number
   leaseDurationMilliseconds?: number
   leaseRenewalIntervalMilliseconds?: number
+  idleDeactivationTimeoutMilliseconds?: number
   maxMailboxLength?: number
   maxPayloadBytes?: number
   maxStateBytes?: number
@@ -107,6 +108,8 @@ export function buildSettings(configuration: SolidObjectsConfiguration): Runtime
     syncPollingIntervalMilliseconds: configuration.syncPollingIntervalMilliseconds ?? 50,
     leaseDurationMilliseconds: configuration.leaseDurationMilliseconds ?? 30_000,
     leaseRenewalIntervalMilliseconds: configuration.leaseRenewalIntervalMilliseconds ?? 10_000,
+    idleDeactivationTimeoutMilliseconds:
+      configuration.idleDeactivationTimeoutMilliseconds ?? 30_000,
     maxMailboxLength: configuration.maxMailboxLength ?? 10_000,
     maxPayloadBytes: configuration.maxPayloadBytes ?? 1_048_576,
     maxStateBytes: configuration.maxStateBytes ?? 5_242_880,
@@ -212,6 +215,12 @@ function validateSettings(settings: RuntimeSettings): void {
   if (settings.leaseDurationMilliseconds <= settings.leaseRenewalIntervalMilliseconds) {
     throw new TypeError("leaseDurationMilliseconds must exceed leaseRenewalIntervalMilliseconds")
   }
+  if (
+    !Number.isFinite(settings.idleDeactivationTimeoutMilliseconds) ||
+    settings.idleDeactivationTimeoutMilliseconds < 0
+  ) {
+    throw new TypeError("idleDeactivationTimeoutMilliseconds must be non-negative")
+  }
   if (
     settings.supervisorMaximumRestartDelayMilliseconds < settings.supervisorRestartDelayMilliseconds
   ) {

src/doctor.ts

@@ -358,7 +358,12 @@ export class Doctor {
         instanceId: message.instance_id,
       })
       if (!turn) throw new Error("doctor could not claim its probe message")
-      await this.runtime.executeTurn(turn)
+      const execution = await this.runtime.executeTurn(turn)
+      await this.runtime.deactivateActor({
+        turn,
+        actor: execution.actor,
+        lifecycle: execution.activated ? "activated" : "unactivated",
+      })
       const completed = await this.runtime.repository.findMessage(message.id)
       if (completed?.result === null || JSON.parse(completed?.result ?? "null") !== value) {
         throw new Error("doctor round trip returned an unexpected result")

src/records.ts

@@ -68,6 +68,13 @@ export interface ClaimedTurn {
   nowMilliseconds: number
 }
 
+export interface ActivationLease {
+  instanceId: string
+  processId: string
+  activationToken: string
+  activationGeneration: bigint
+}
+
 export interface EnqueueInput {
   actorType: string
   actorId: string