atomic-queues 1.6.2 → 2.0.1

package/README.md

@@ -26,54 +26,29 @@
 <p align="center">
   <img src="https://img.shields.io/npm/v/atomic-queues?style=flat-square&color=cb3837" alt="npm version" />
   <img src="https://img.shields.io/badge/NestJS-11-ea2845?style=flat-square&logo=nestjs" alt="NestJS 11" />
-  <img src="https://img.shields.io/badge/BullMQ-5-3c873a?style=flat-square" alt="BullMQ 5" />
   <img src="https://img.shields.io/badge/Redis-7-dc382d?style=flat-square&logo=redis&logoColor=white" alt="Redis 7" />
   <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT License" />
 </p>
 
 ---
 
-## Why atomic-queues?
+## What is atomic-queues?
 
-Distributed locks (Redlock, advisory locks, optimistic locking) all share the same fundamental flaw: **contention collapse**. When multiple pods fight for the same lock simultaneously, they spend more time retrying failed acquisitions than doing actual work. The harder you push, the slower they go.
+**A distributed virtual actor runtime for Node.js, built entirely on Redis primitives.**
 
-**atomic-queues** eliminates contention entirely. Instead of locking, each entity gets its own dedicated BullMQ queue. Operations execute sequentially — back-to-back with zero wasted cycles. There's nothing to contend over.
+Think [Microsoft Orleans](https://learn.microsoft.com/en-us/dotnet/orleans/) or [Akka](https://akka.io/) — but for the NestJS ecosystem, requiring nothing beyond a Redis instance you probably already have.
 
-### atomic-queues vs Redlock
+Messages addressed to the same entity execute sequentially. Messages addressed to different entities execute in parallel. No distributed locks. No worker processes. No message broker. No BullMQ.
 
-| | Redlock | atomic-queues |
-|---|---|---|
-| **Architecture** | Distributed mutex (quorum-based) | Per-entity queue (sequential) |
-| **Under contention** | Degrades — retry storms, backoff delays | **Constant** — jobs queue up, execute instantly |
-| **Failure mode** | Silent double-execution (clock drift) | Job stuck in queue (visible, retryable) |
-| **Split-brain risk** | Yes (timing assumptions) | **Impossible** (serial queue) |
-| **Warm-path overhead** | Acquire + release per op | **0 Redis calls** (in-memory hot cache) |
-| **Cold-start** | None | One-time per entity |
-| **Multi-pod scaling** | Contention increases with pods | **Throughput increases with pods** |
+```
+npm install atomic-queues ioredis
+```
 
 ---
 
-## Table of Contents
-
-- [Why atomic-queues?](#why-atomic-queues)
-- [How It Works](#how-it-works)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Commands & Decorators](#commands--decorators)
-- [Configuration](#configuration)
-- [Distributed Worker Lifecycle](#distributed-worker-lifecycle)
-- [Complete Example](#complete-example)
-- [Advanced: Custom Worker Processors](#advanced-custom-worker-processors)
-- [Performance](#performance)
-- [License](#license)
+## The Problem
 
----
-
-## How It Works
-
-### The Problem
-
-Every distributed system eventually hits this:
+Every distributed system eventually builds toward one of two failure modes: **state corruption** from concurrent mutations on the same entity, or **throughput collapse** from the locking mechanisms used to prevent it.
 
 ```
 Time    Request A                    Request B                    Database
@@ -86,110 +61,80 @@ T₃                                   UPDATE: $100 − $80 = $20     −$60
 Result: Balance is −$60. Both withdrawals succeed. Integrity violated.
 ```
 
-### The Solution
+The standard answers — `SELECT ... FOR UPDATE`, optimistic locking with retries, distributed locks via Redlock or ZooKeeper, serializable transactions — all trade throughput for correctness. Under load, they become bottlenecks. Across services, they become nightmares. And every team ends up inventing some ad-hoc combination of them, poorly, under production pressure.
+
+## The Insight
 
-atomic-queues routes operations through per-entity queues. Same entity → same queue → sequential execution. Different entities → parallel queues → full throughput.
+The problem disappears if you change *when* serialization happens. Instead of serializing at the database level (row locks, transaction isolation), serialize at the **message level**: route all operations for a given entity through a single ordered log, and process that log sequentially. Different entities maintain independent logs with zero coordination between them.
+
+This is the virtual actor model. It's not new — Erlang/OTP has used it since the 1980s, Orleans shipped it in 2014, Akka has been doing it on the JVM for over a decade. What *is* new is implementing it with nothing beyond Redis and making it native to the NestJS ecosystem.
 
 ```
                         ┌─────────────────────────────────────────────────┐
   Request A ─┐          │           Entity: account-42                    │
              │          │  ┌──────┐  ┌──────┐  ┌──────┐                  │
-  Request B ─┼─► Route ─┼─►│ Op 1 │─►│ Op 2 │─►│ Op 3 │─► [Worker] ──┐  │
-             │          │  └──────┘  └──────┘  └──────┘               │  │
-  Request C ─┘          │                    Sequential ◄─────────────┘  │
+  Request B ─┼─► Route ─┼─►│ Msg1 │─►│ Msg2 │─►│ Msg3 │─► [Executor] ─┐ │
+             │          │  └──────┘  └──────┘  └──────┘               │ │
+  Request C ─┘          │                     Sequential ◄────────────┘ │
                         └─────────────────────────────────────────────────┘
 
-                        ┌─────────────────────────────────────────────────┐
-  Request D ─┐          │           Entity: account-99                    │
-             │          │  ┌──────┐  ┌──────┐                            │
-  Request E ─┼─► Route ─┼─►│ Op 1 │─►│ Op 2 │─────────► [Worker] ──┐    │
-             │          │  └──────┘  └──────┘                       │    │
-  Request F ─┘          │                    Sequential ◄───────────┘    │
-                        └─────────────────────────────────────────────────┘
-
-                        ▲ These two queues run in PARALLEL across pods ▲
+  Meanwhile, account-99, order-7, user-abc — all execute
+  in parallel on the same cluster, completely independent.
 ```
 
-**Key properties:**
-- **One worker per entity** — enforced via Redis heartbeat TTL. No duplicates, ever.
-- **Auto-spawn** — workers materialize when jobs arrive, on the pod that sees them first.
-- **Auto-terminate** — idle workers shut down after a configurable timeout.
-- **Self-healing** — node failure → heartbeat expires → worker respawns on a healthy pod.
-- **Distributed** — workers spread across all pods via atomic `SET NX` claim. No leader election, no single point of failure.
+This eliminates an entire class of bugs — lost updates, dirty reads, write skew, phantom reads on hot entities — without pessimistic locks, without optimistic retries, and without the `SELECT ... FOR UPDATE` that your DBA tells you not to use under load. The entity itself becomes the consistency boundary, and the consistency is structural rather than transactional.
 
 ---
 
-## Installation
-
-```bash
-npm install atomic-queues
-```
+## How It Works
 
-BullMQ, ioredis, and `@nestjs/bullmq` are bundled — no extra installs needed.
+### Entities and messages
 
-**Peer dependencies** (provided by your NestJS app): `@nestjs/common` 10+, `@nestjs/core` 10+, `reflect-metadata`, `rxjs` 7+. Optional: `@nestjs/cqrs` (for auto-routing commands/queries).
+Everything in atomic-queues is an **entity** that receives **messages**. An entity is identified by a type and an ID — `account:a-42`, `order:o-17`, `user:u-abc`. A message is a command or query addressed to a specific entity instance. You define this relationship with two decorators:
 
----
+```typescript
+@EntityType('account')
+export class WithdrawCommand {
+  constructor(
+    @QueueEntityId() public readonly accountId: string,
+    public readonly amount: number,
+  ) {}
+}
+```
 
-## Quick Start
+That's the entire contract. `@EntityType` says "this message targets the `account` entity type." `@QueueEntityId()` says "the value of `accountId` is the entity instance ID." When you enqueue this command, the runtime routes it to the log for `account:{accountId}` and guarantees sequential execution against that specific entity instance, cluster-wide.
 
-### 1. Configure the Module
+### Two levels of abstraction
 
-```typescript
-import { Module } from '@nestjs/common';
-import { CqrsModule } from '@nestjs/cqrs';
-import { AtomicQueuesModule } from 'atomic-queues';
+atomic-queues gives you two ways to handle messages, and they're not different systems — they're two levels of abstraction over the same dispatch engine.
 
-@Module({
-  imports: [
-    CqrsModule,
-    AtomicQueuesModule.forRoot({
-      redis: { host: 'localhost', port: 6379 },
-      keyPrefix: 'myapp',
-      entities: {
-        account: {
-          queueName: (id) => `account-${id}-queue`,
-          workerName: (id) => `account-${id}-worker`,
-          maxWorkersPerEntity: 1,
-          idleTimeoutSeconds: 15,
-        },
-      },
-    }),
-  ],
-})
-export class AppModule {}
-```
+**Actors** are the foundational primitive. An actor class *is* an entity — its fields are the state, its methods are message handlers. The runtime manages its lifecycle: activate on first message, evict from memory on idle, persist state to Redis automatically, restore on reactivation.
 
-> **Tip:** The `entities` config is optional. Without it, default naming applies: `{keyPrefix}:{entityType}:{entityId}:queue`.
+```typescript
+@Actor('account')
+@Injectable()
+export class AccountActor {
+  private balance = 0;
 
-<details>
-<summary><strong>Async configuration (ConfigService)</strong></summary>
+  @On(DepositCommand)
+  async deposit(msg: DepositCommand) {
+    this.balance += msg.amount;
+    return this.balance;
+  }
 
-```typescript
-AtomicQueuesModule.forRootAsync({
-  imports: [ConfigModule],
-  useFactory: (config: ConfigService) => ({
-    redis: { url: config.get('REDIS_URL') },
-    keyPrefix: 'myapp',
-    entities: {
-      account: {
-        queueName: (id) => `account-${id}-queue`,
-        workerName: (id) => `account-${id}-worker`,
-      },
-    },
-  }),
-  inject: [ConfigService],
-}),
+  @On(WithdrawCommand)
+  async withdraw(msg: WithdrawCommand) {
+    if (this.balance < msg.amount) throw new InsufficientFunds();
+    this.balance -= msg.amount;
+    return this.balance;
+  }
+}
 ```
 
-</details>
-
-### 2. Define Commands
+**CQRS handlers** are the convenience layer for teams using `@nestjs/cqrs`. You don't write actor classes — you write standard `@CommandHandler` and `@QueryHandler` classes exactly as NestJS CQRS prescribes, and atomic-queues intercepts the dispatch to route them through the same per-entity log and gate system. The handler code doesn't change. The guarantee changes — instead of executing inline on whatever request thread happens to call `commandBus.execute()`, your handler now executes sequentially per entity, cluster-wide.
 
 ```typescript
-import { QueueEntity, QueueEntityId } from 'atomic-queues';
-
-@QueueEntity('account')
+@EntityType('account')
 export class WithdrawCommand {
   constructor(
     @QueueEntityId() public readonly accountId: string,
@@ -197,409 +142,324 @@ export class WithdrawCommand {
   ) {}
 }
 
-@QueueEntity('account')
-export class DepositCommand {
-  constructor(
-    @QueueEntityId() public readonly accountId: string,
-    public readonly amount: number,
-  ) {}
+@CommandHandler(WithdrawCommand)
+export class WithdrawHandler implements ICommandHandler<WithdrawCommand> {
+  async execute(cmd: WithdrawCommand) {
+    // This runs sequentially per account — cluster-wide.
+    // No locks. No transactions. The dispatch engine guarantees it.
+  }
 }
 ```
 
-### 3. Write Handlers (standard @nestjs/cqrs)
+The library auto-discovers `@CommandHandler` and `@QueryHandler` classes at boot and wires them into the dispatch pipeline. Your existing CQRS architecture gets per-entity sequential guarantees without changing a single handler. The CQRS surface *calls into the actor runtime* — it's not a separate execution path.
 
-```typescript
-import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
+### Enqueuing messages
 
-@CommandHandler(WithdrawCommand)
-export class WithdrawHandler implements ICommandHandler<WithdrawCommand> {
-  constructor(private readonly repo: AccountRepository) {}
+```typescript
+// Fire-and-forget
+await queueBus.enqueue(new WithdrawCommand(accountId, 100));
 
-  async execute({ accountId, amount }: WithdrawCommand) {
-    // SAFE: No race conditions. Sequential execution per account.
-    const account = await this.repo.findById(accountId);
+// Enqueue and block until result
+const balance = await queueBus.enqueueAndWait(new GetBalanceQuery(accountId));
 
-    if (account.balance < amount) {
-      throw new InsufficientFundsError(accountId, account.balance, amount);
-    }
+// Scoped to an entity type
+await queueBus.forEntity('account').enqueueBulk([charge1, charge2, charge3]);
 
-    account.balance -= amount;
-    await this.repo.save(account);
-  }
-}
+// Actor-style direct send
+await actorSystem.send('account', accountId, new DepositCommand(100));
+const balance = await actorSystem.sendAndWait('account', accountId, new GetBalanceQuery());
 ```
 
-### 4. Enqueue Jobs
+---
 
-```typescript
-import { Injectable } from '@nestjs/common';
-import { QueueBus } from 'atomic-queues';
+## The Dispatch Engine
 
-@Injectable()
-export class AccountService {
-  constructor(private readonly queueBus: QueueBus) {}
+Under every API call is the same pipeline: **message → Redis log → Lua scheduler → gate → executor → handler**. Understanding this pipeline is key to understanding what atomic-queues actually guarantees and why it can guarantee it without locks.
 
-  async withdraw(accountId: string, amount: number) {
-    await this.queueBus.enqueue(new WithdrawCommand(accountId, amount));
-  }
-}
-```
+### Per-entity message logs
 
-**That's it.** The library automatically:
-1. Creates a queue for each `accountId` when jobs arrive
-2. Spawns a worker (spread across pods) to process jobs sequentially
-3. Routes jobs to the correct `@CommandHandler` via CQRS
-4. Terminates idle workers after the configured timeout
-5. Self-heals if a pod dies (heartbeat expires → respawn elsewhere)
+When you call `enqueue()`, the message is serialized to JSON and appended to a Redis list (`LPUSH aq:log:account:a-42`), and the entity key is added to a global ready set (`SADD aq:ready account:a-42`). A pub/sub notification wakes the executor pool. Three Redis commands, pipelined in one round-trip.
 
----
+The log is the source of truth for ordering. Redis lists are FIFO — `LPUSH` appends to the head, `RPOP` consumes from the tail. Messages for the same entity are always processed in enqueue order.
 
-## Commands & Decorators
+### The dispatch gate
 
-### `@QueueEntity(entityType, entityIdProperty?)`
+The core consistency primitive is the **dispatch gate** — a Redis key per entity (`SET aq:gate:account:a-42 <token> EX 30 NX`). The `NX` flag means only one executor can acquire it. The `EX` TTL means a crashed executor releases it automatically. This is not a distributed lock in the Redlock sense — there's no quorum, no retry loop, no backoff. If the gate is held, the scheduler moves on to the next ready entity. Zero contention between entities, zero blocking within the scheduling loop.
 
-Marks a command/query class for queue routing. The optional second argument specifies which property holds the entity ID — this is the simplest approach when you don't want to decorate individual properties.
+### Atomic Lua scheduling
 
-```typescript
-// Option 1: Explicit property name (no @QueueEntityId needed)
-@QueueEntity('account', 'accountId')
-export class TransferCommand {
-  constructor(
-    public readonly accountId: string,
-    public readonly toAccountId: string,
-    public readonly amount: number,
-  ) {}
-}
+A single Lua script runs atomically in Redis to perform the entire dispatch cycle:
 
-// Option 2: Rely on module-level defaultEntityId from entities config
-@QueueEntity('account')
-export class DepositCommand {
-  constructor(
-    public readonly accountId: string,  // Matched by entities.account.defaultEntityId
-    public readonly amount: number,
-  ) {}
-}
-```
+1. Sample entities from the ready set (`SRANDMEMBER` with batch size 32)
+2. Try to acquire the gate for each candidate (`SET NX EX`)
+3. On first successful acquisition, pop the next message from that entity's log (`RPOP`)
+4. Remove the entity from the ready set if its log is now empty
 
-### `@QueueEntityId()`
+Because Lua scripts execute atomically in Redis, the pick → gate acquisition → message pop sequence cannot be interleaved by another executor on another node. This is what eliminates race conditions — not locks, but atomicity at the Redis command level.
 
-Marks the property that contains the entity ID. One per class. Use this when you need per-command control over which property is the entity ID, or when you can't use the two-argument `@QueueEntity` shorthand.
+### Shared executor pool
 
-```typescript
-@QueueEntity('account')
-export class TransferCommand {
-  constructor(
-    @QueueEntityId() public readonly accountId: string,  // Routes to this account's queue
-    public readonly targetAccountId: string,
-    public readonly amount: number,
-  ) {}
-}
-```
+Traditional queue systems spawn a worker per queue or per entity type. With thousands of entities, that means thousands of blocking Redis connections, thousands of event loops, and a scaling problem that grows linearly with your domain model.
+
+atomic-queues uses a **shared executor pool** — a configurable number of concurrent executors per node that dispatch messages from *any* ready entity. One pool can service millions of distinct entities. The pool self-regulates: it drains the ready set until empty or until the concurrency limit is hit, then sleeps until the next pub/sub tickle wakes it. There are no workers to spawn, monitor, or auto-scale.
+
+### Gate refresh for long-running handlers
+
+If a handler runs longer than the gate TTL, the gate doesn't expire — the executor pool runs a background interval that extends the TTL while the handler is still executing. This prevents false recovery (another node re-dispatching the same message) without requiring an unreasonably large TTL as the safety default.
+
+### Multiplexed result collection
+
+Request-reply (`enqueueAndWait` / `sendAndWait`) uses a single `PSUBSCRIBE` connection per node for all concurrent result waits. Hundreds or thousands of pending results share one TCP connection to Redis, routed to the correct promise via correlation ID. No connection-per-call, no connection pool exhaustion, no subscriber amplification.
+
+---
+
+## Cross-Service Communication
+
+This is where atomic-queues stops being a "queue library" and becomes a **distributed coordination primitive**.
+
+### The problem it solves
+
+In a microservices architecture, the standard way for Service A to tell Service B to do something is: define a gRPC/REST contract, deploy an API gateway or service mesh, handle serialization, implement retries, manage circuit breakers, and hope the schema stays in sync across repos. For async communication, add a message broker (RabbitMQ, Kafka, SQS), define topic/queue naming conventions, implement dead-letter handling, and build consumer groups.
 
-> **Entity ID resolution order:** `@QueueEntityId()` decorator > `@QueueEntity('type', 'prop')` second argument > `@WorkerProcessor({ defaultEntityId })` > `entities[type].defaultEntityId` in module config.
+atomic-queues replaces all of that with Redis.
 
-### `@WorkerProcessor(options)`
+### How it works
 
-Optional. Define a processor class for custom job handling on top of CQRS auto-routing.
+Enable the distributed registry and any service connected to the same Redis instance can send typed messages to any entity — regardless of which service owns the handler.
 
 ```typescript
-@WorkerProcessor({
-  entityType: 'account',
-  queueName: (id) => `account-${id}-queue`,
-  workerName: (id) => `account-${id}-worker`,
-  maxWorkersPerEntity: 1,
-  idleTimeoutSeconds: 15,
+// billing-service: defines and handles the entity
+AtomicQueuesModule.forRoot({
+  redis: { url: process.env.REDIS_URL },
+  registry: { enabled: true, serviceName: 'billing-service' },
 })
-@Injectable()
-export class AccountProcessor {
-  @JobHandler('special-audit')
-  async handleAudit(job: Job, entityId: string) { ... }
-}
+
+// payments-service: sends to it (shared Redis, no code dependency on billing)
+await queueBus.enqueue(new WithdrawCommand(accountId, 100));
 ```
 
-### `@JobHandler(jobName)` / `@JobHandler('*')`
+When `billing-service` starts, it scans its own `@Actor`, `@CommandHandler`, and `@QueryHandler` classes and publishes **entity contracts** to Redis — a JSON document listing the entity type, accepted messages, and optional JSON schemas, refreshed via heartbeat TTL. When `payments-service` enqueues a message, the registry validates it at the call site *before* it enters the log: entity type exists, message name is accepted, payload matches schema. Errors are immediate and descriptive — not silent dead letters discovered hours later in a DLQ dashboard.
 
-Custom job handlers on a `@WorkerProcessor`. The wildcard `'*'` catches anything not matched by a specific handler.
+### What this replaces
 
----
+Think about what you no longer need:
 
-## Configuration
+**No API gateway between services.** Messages go directly into the entity's log via Redis. The "endpoint" is the entity type and message name, not a URL.
+
+**No message broker.** Redis is the transport, the ordering guarantee, and the persistence layer. You don't need RabbitMQ, Kafka, or SQS to get async cross-service communication with ordering guarantees.
+
+**No schema registry as a separate service.** The entity contracts live in Redis alongside the message logs. Schema validation happens at the call site. Zod schemas on the producer side serialize to JSON Schema in the registry and validate on every enqueue.
+
+**No service discovery.** The registry *is* service discovery. When a service starts, it publishes what it handles. When a service stops, its registrations TTL out. Other services discover capabilities by reading the registry.
+
+**No serialization framework.** Messages are JSON. The wire protocol is three Redis commands. No Protobuf compilation step, no `.proto` files, no code generation from IDL. (Though atomic-queues does offer codegen from the live registry — it generates TypeScript interfaces so Service A gets compile-time type safety for messages destined to Service B, without importing Service B's code.)
+
+**No separate dead-letter infrastructure.** Failed messages are dead-lettered per entity type in Redis, queryable via the same connection.
+
+### Schema validation
+
+Attach Zod schemas to message classes for runtime safety across service boundaries:
 
 ```typescript
-AtomicQueuesModule.forRoot({
-  // ── Redis connection ──────────────────────────────────────
-  redis: {
-    host: 'redis',
-    port: 6379,
-    password: 'secret',       // optional
-  },
+import { Schema } from 'atomic-queues';
+import { z } from 'zod';
+
+@Schema(z.object({
+  accountId: z.string().uuid(),
+  amount: z.number().positive(),
+}))
+@EntityType('account')
+export class WithdrawCommand {
+  @QueueEntityId() public readonly accountId: string;
+  public readonly amount: number;
+}
+```
 
-  // ── Global settings ───────────────────────────────────────
-  keyPrefix: 'myapp',          // Redis key namespace (default: 'aq')
-  enableCronManager: true,     // Legacy cron-based scaling (optional)
-  cronInterval: 5000,          // Cron tick interval in ms
-
-  // ── Worker defaults ───────────────────────────────────────
-  workerDefaults: {
-    concurrency: 1,            // Jobs processed concurrently per worker
-    stalledInterval: 1000,     // ms between stalled-job checks
-    lockDuration: 30000,       // ms a job is locked during processing
-    heartbeatTTL: 3,           // Heartbeat key TTL in seconds
-  },
+The Zod schema serializes to JSON Schema and stores in the registry. Every service validates payloads against it — even services that don't import your code, even services written in a different language that read the registry directly from Redis.
 
-  // ── Per-entity configuration (optional) ───────────────────
-  entities: {
-    account: {
-      queueName: (id) => `account-${id}-queue`,
-      workerName: (id) => `account-${id}-worker`,
-      maxWorkersPerEntity: 1,
-      idleTimeoutSeconds: 15,
-
-      // Fallback property name for entity ID extraction.
-      // Used when a command has no @QueueEntityId() decorator
-      // and no second argument to @QueueEntity().
-      defaultEntityId: 'accountId',
+### Entity co-ownership
 
-      workerConfig: {          // Override workerDefaults per entity
-        concurrency: 1,
-        lockDuration: 60000,
-      },
-    },
-  },
-});
+Multiple services can handle different message types on the same entity. Service A handles `DepositCommand` and `WithdrawCommand` on the `account` entity type. Service B handles `FreezeAccountCommand` on the same entity type. The registry merges their contracts automatically. The dispatch gate still ensures single-writer semantics per entity instance, regardless of which service's executor picks up the message.
+
+### Contract codegen
+
+Generate typed interfaces from the live registry:
+
+```bash
+REDIS_URL=redis://localhost:6379 npx atomic-queues generate --ts --output ./generated/contracts.ts
 ```
 
+Also supports `--json-schema` for language-agnostic schema export and `--snapshot` for full registry dumps.
+
 ---
 
-## Distributed Worker Lifecycle
+## Redis *is* the Protocol
+
+This is the most important architectural decision in the project, and it has implications that go far beyond NestJS.
 
-Workers in atomic-queues have a fully automated lifecycle, distributed across all pods with no leader election:
+The wire protocol is [fully documented](./WIRE-PROTOCOL.md), intentionally simple, and versioned with breaking-change semantics. Enqueuing a message is three Redis commands:
 
 ```
-  Job arrives                   SET NX claim
-  on any pod  ──────►  ┌──────────────────────┐
-                        │  Pod claims worker?   │
-                        └──────┬───────┬───────┘
-                           YES │       │ NO (another pod won)
-                               ▼       ▼
-                        ┌────────┐  ┌──────────────┐
-                        │ Spawn  │  │ Wait — other │
-                        │ worker │  │ pod handles  │
-                        │ locally│  └──────────────┘
-                        └───┬────┘
-                            ▼
-                     ┌──────────────┐
-                     │  Processing  │◄──── Heartbeat refresh (pipeline)
-                     │  jobs back-  │      every 1s (1 Redis round-trip)
-                     │  to-back     │
-                     └──────┬───────┘
-                            │ No jobs for idleTimeoutSeconds
-                            ▼
-                     ┌──────────────┐
-                     │  Idle sweep  │──── Hot cache eviction
-                     │  closes      │     Heartbeat keys cleaned up
-                     │  worker      │
-                     └──────────────┘
+LPUSH  aq:log:account:a-1  '<message JSON>'
+SADD   aq:ready  account:a-1
+PUBLISH aq:tickle  1
 ```
 
-### Hot Cache
+**Any language with a Redis client is a first-class citizen.** A Python data pipeline can enqueue commands to a NestJS-hosted actor. A Go microservice can fire events at entities defined in TypeScript. A Rust executor can run the same Lua scheduling script and compete for gates on equal terms with the Node.js executor pool. A Bash script can trigger a workflow.
 
-After a worker is confirmed alive, subsequent job arrivals for that entity hit an **in-memory cache** — zero Redis calls on the warm path. This eliminates the per-job Redis overhead that plagues lock-based approaches.
+This is not a feature of any existing mainstream actor framework. Orleans requires the Orleans silo. Akka requires the JVM. Temporal requires the Temporal server with its own database. All of them are monoglot execution environments — actors must be written in the framework's language.
 
-| Path | Redis calls | When |
-|---|---|---|
-| **Hot** (cache hit) | 0 | Worker known alive |
-| **Warm** (cache miss) | 1 (`EXISTS`) | First time seeing entity |
-| **Cold** (no worker) | 1 (`SET NX`) | Worker needs creation |
+atomic-queues is **polyglot by construction**. The coordination happens in Redis, not in the runtime. Any process that speaks the wire protocol participates on equal terms, and the [WIRE-PROTOCOL.md](./WIRE-PROTOCOL.md) includes a complete Python reference client to prove it.
 
-### SpawnQueueService
+This opens architectures that are genuinely difficult to build otherwise:
 
-For multi-pod deployments, the `SpawnQueueService` distributes worker creation across all pods via a shared BullMQ spawn queue. The **direct local spawn** path bypasses this queue entirely — the pod that first sees a job for a new entity claims it with an atomic `SET NX` and spawns the worker locally.
+- **Ingest in Go, process in Node.js, analyze in Python.** Each layer speaks Redis. The entity logs are the integration boundary.
+- **Rust executors for CPU-hot-path actors.** The same Lua scheduler, the same gates, the same entity logs. The Rust process is just another executor that happens to be faster. The Node.js side doesn't know or care.
+- **Gradual migration.** Move one entity type's handlers to a different service, a different language, or a different infrastructure — without touching any other service's code. The entity contract in the registry is the interface, not the import statement.
+- **Edge coordination.** An IoT device with a Redis client and 3 commands of knowledge can participate in the same entity model as your cloud services.
 
 ---
 
-## Complete Example
-
-A banking service with withdrawals, deposits, and cross-account transfers:
+## Quick Start
 
 ```typescript
-// ── Module ──────────────────────────────────────────────
 import { Module } from '@nestjs/common';
-import { CqrsModule } from '@nestjs/cqrs';
 import { AtomicQueuesModule } from 'atomic-queues';
 
 @Module({
   imports: [
-    CqrsModule,
     AtomicQueuesModule.forRoot({
-      redis: { host: 'redis', port: 6379 },
-      keyPrefix: 'banking',
-      entities: {
-        account: {
-          queueName: (id) => `account-${id}-queue`,
-          workerName: (id) => `account-${id}-worker`,
-          maxWorkersPerEntity: 1,
-          idleTimeoutSeconds: 15,
-        },
-      },
+      redis: { host: 'localhost', port: 6379 },
     }),
   ],
-  providers: [
-    AccountService,
-    WithdrawHandler,
-    DepositHandler,
-    TransferHandler,
-  ],
 })
-export class BankingModule {}
+export class AppModule {}
+```
 
-// ── Commands ────────────────────────────────────────────
-import { QueueEntity, QueueEntityId } from 'atomic-queues';
+Define a command and enqueue it:
 
-@QueueEntity('account')
+```typescript
+@EntityType('account')
 export class WithdrawCommand {
   constructor(
     @QueueEntityId() public readonly accountId: string,
     public readonly amount: number,
-    public readonly transactionId: string,
   ) {}
 }
 
-@QueueEntity('account')
-export class DepositCommand {
-  constructor(
-    @QueueEntityId() public readonly accountId: string,
-    public readonly amount: number,
-    public readonly source: string,
-  ) {}
-}
+@Injectable()
+export class PaymentService {
+  constructor(private readonly queueBus: QueueBus) {}
 
-@QueueEntity('account')
-export class TransferCommand {
-  constructor(
-    @QueueEntityId() public readonly accountId: string,
-    public readonly toAccountId: string,
-    public readonly amount: number,
-  ) {}
+  async withdraw(accountId: string, amount: number) {
+    await this.queueBus.enqueue(new WithdrawCommand(accountId, amount));
+  }
 }
+```
 
-// ── Handlers ────────────────────────────────────────────
-import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
+The command is appended to `account:{accountId}`'s message log and executed sequentially by the shared executor pool. No handler registration, no worker setup, no queue configuration.
 
-@CommandHandler(WithdrawCommand)
-export class WithdrawHandler implements ICommandHandler<WithdrawCommand> {
-  constructor(private readonly repo: AccountRepository) {}
+---
 
-  async execute({ accountId, amount }: WithdrawCommand) {
-    const account = await this.repo.findById(accountId);
-    if (account.balance < amount) throw new InsufficientFundsError();
-    account.balance -= amount;
-    await this.repo.save(account);
-  }
-}
+## Configuration
 
-@CommandHandler(TransferCommand)
-export class TransferHandler implements ICommandHandler<TransferCommand> {
-  constructor(
-    private readonly repo: AccountRepository,
-    private readonly queueBus: QueueBus,
-  ) {}
+```typescript
+AtomicQueuesModule.forRoot({
+  redis: { host: 'localhost', port: 6379 },
 
-  async execute({ accountId, toAccountId, amount }: TransferCommand) {
-    // Debit source (we're in source account's queue — safe)
-    const source = await this.repo.findById(accountId);
-    if (source.balance < amount) throw new InsufficientFundsError();
-    source.balance -= amount;
-    await this.repo.save(source);
-
-    // Credit destination (enqueued to destination's queue — also safe)
-    await this.queueBus.enqueue(
-      new DepositCommand(toAccountId, amount, `transfer:${accountId}`),
-    );
-  }
-}
+  executor: {
+    poolSize: 1,          // concurrent executors per node
+    gateTTL: 30,          // seconds before gate expires (safety net)
+  },
 
-// ── Controller ──────────────────────────────────────────
-import { Controller, Post, Body, Param } from '@nestjs/common';
-import { QueueBus } from 'atomic-queues';
+  entities: {
+    account: {
+      defaultEntityId: 'accountId',
+      gateTTL: 60,
+      retry: { maxAttempts: 5, backoff: 'exponential', backoffDelay: 2000 },
+      actorIdleTimeout: 120000,
+      statePersistence: true,
+    },
+  },
 
-@Controller('accounts')
-export class AccountController {
-  constructor(private readonly queueBus: QueueBus) {}
+  registry: {
+    enabled: false,
+    serviceName: 'my-service',
+    schemaValidation: false,
+    heartbeatInterval: 10000,
+    registrationTTL: 30,
+  },
 
-  @Post(':id/withdraw')
-  async withdraw(@Param('id') id: string, @Body() body: { amount: number }) {
-    await this.queueBus.enqueue(new WithdrawCommand(id, body.amount, uuid()));
-    return { queued: true };
-  }
+  keyPrefix: 'aq',
+  verbose: false,
+})
+```
 
-  @Post(':id/transfer')
-  async transfer(
-    @Param('id') id: string,
-    @Body() body: { to: string; amount: number },
-  ) {
-    await this.queueBus.enqueue(new TransferCommand(id, body.to, body.amount));
-    return { queued: true };
-  }
-}
+Optional peer dependencies:
+
+```bash
+npm install @nestjs/cqrs          # for CQRS handler auto-wiring
+npm install zod zod-to-json-schema # for schema validation in the registry
 ```
 
 ---
 
-## Advanced: Custom Worker Processors
+## Guarantees
 
-For cases where CQRS auto-routing isn't enough, define a `@WorkerProcessor` with explicit `@JobHandler` methods:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { WorkerProcessor, JobHandler } from 'atomic-queues';
-import { Job } from 'bullmq';
-
-@WorkerProcessor({
-  entityType: 'account',
-  queueName: (id) => `account-${id}-queue`,
-  workerName: (id) => `account-${id}-worker`,
-  maxWorkersPerEntity: 1,
-  idleTimeoutSeconds: 15,
-})
-@Injectable()
-export class AccountProcessor {
-  @JobHandler('high-priority-audit')
-  async handleAudit(job: Job, entityId: string) {
-    // Specific handler for this job type
-  }
+| Guarantee | Scope | Mechanism |
+|---|---|---|
+| FIFO per entity | Cluster-wide | Redis list (`LPUSH`/`RPOP`) |
+| Single-writer per entity | Cluster-wide | Gate key (`SET NX EX`) |
+| At-least-once delivery | Per message | Retry on gate TTL expiry |
+| Parallel across entities | Per node | Executor pool concurrency |
+| Durability | Per message | Redis persistence (AOF/RDB) |
 
-  @JobHandler('*')
-  async handleAll(job: Job, entityId: string) {
-    // Wildcard — catches everything not explicitly handled
-    // Falls back to CQRS routing automatically when not defined
-  }
-}
-```
+### What this does NOT guarantee
 
-> **Priority order:** Explicit `@JobHandler` → CQRS auto-routing (`@JobCommand`/`@JobQuery`) → Wildcard handler
+**Exactly-once processing.** Like every distributed message system — Orleans, Akka, Temporal, Kafka — handlers must be idempotent. If an executor crashes mid-processing, the gate TTL expires and the message retries on another node. This is a fundamental constraint of distributed systems, not a limitation of the library.
 
 ---
 
-## Performance
+## How It Compares
 
-### Why it's fast
+| Capability | BullMQ | Temporal | atomic-queues |
+|---|---|---|---|
+| Per-entity ordering | Manual (named queues) | Workflow-scoped | Built-in, zero config |
+| Cross-entity parallelism | Worker pools | Worker pools | Shared executor pool |
+| Stateful entities | No | Workflow state | Virtual actors |
+| Cross-service messaging | Shared queue names | gRPC | Redis registry + codegen |
+| Polyglot clients | JS/TS only | SDK per language | Any Redis client (3 commands) |
+| Infrastructure required | Redis | Temporal server + DB | Redis only |
+| Distributed locks needed | Yes, for ordering | Internal | None — gates are non-contending |
+| Service discovery | External | Built-in | Built-in (registry) |
+| Schema validation | No | Protobuf | Zod → JSON Schema |
 
-1. **Zero contention** — no locks, no retries, no backoff. Jobs queue and execute.
-2. **Hot cache** — after first check, subsequent job arrivals for an entity incur 0 Redis calls.
-3. **Direct local spawn** — atomic `SET NX` claim, local worker creation. No queue round-trip.
-4. **Pipelined heartbeats** — heartbeat refresh uses a single Redis pipeline (1 round-trip for 2 keys).
-5. **O(1) worker existence check** — global alive key replaces `KEYS` pattern scan.
+---
 
-### When to use what
+## Decorator Reference
 
-| Use case | Recommendation |
+| Decorator | Purpose |
 |---|---|
-| Per-entity operations that must be serialized (payments, inventory, game state) | **atomic-queues** |
-| Rare, low-frequency mutual exclusion (config updates, migrations) | Redlock / advisory locks |
-| Exactly-once semantics with audit trail | **atomic-queues** (BullMQ job IDs) |
-| Sub-millisecond synchronous response required | Redlock (synchronous acquire) |
-| Multi-pod, many entities, sustained load | **atomic-queues** (contention-free scaling) |
+| `@EntityType('type')` | Route a message to an entity type |
+| `@QueueEntityId()` | Mark the property holding the entity ID |
+| `@QueueEntity('type', 'prop')` | Combined entity type + ID |
+| `@Actor('type')` | Declare a virtual actor class |
+| `@On(MessageClass)` | Handle a message type on an actor |
+| `@Schema(zodSchema)` | Attach a Zod schema for registry validation |
+
+---
+
+## Migrating from V1
+
+V2 is a full rewrite of the internals. BullMQ is removed. Workers are removed. The public API is largely preserved.
+
+**What stays the same**: `@EntityType`, `@QueueEntityId`, `@QueueEntity`, `queueBus.enqueue()`, `queueBus.forEntity()`, `queueBus.enqueueAndWait()`.
+
+**What's removed**: `@WorkerProcessor`, `@JobHandler`, `@EntityScaler`, `@OnSpawnWorker`, `@OnTerminateWorker`, `@GetActiveEntities`, `@GetDesiredWorkerCount`, `.forProcessor()`. All worker and scaling concepts are gone.
+
+**What's new**: `@Actor`, `@On`, `@Schema`, `ActorSystem`, `RegistryService`, distributed registry, codegen CLI.
+
+**Migration steps**: (1) remove all `@WorkerProcessor` classes — replace with `@Actor` or configure entity defaults in module config; (2) remove all scaling decorators; (3) run the data migration script to drain in-flight BullMQ jobs to the new log format; (4) remove `bullmq` and `@nestjs/bullmq` from your dependencies.
 
 ---