atomic-queues 1.6.1 → 2.0.0

package/README.md

@@ -26,52 +26,21 @@
 <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. Sequential per entity, parallel across entities, zero contention. Three interchangeable API surfaces — queues, CQRS, and actors — backed by one Redis-based execution engine.
 
-**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.
-
-### atomic-queues vs Redlock
-
-| | 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** |
-
----
-
-## 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)
+No BullMQ. No workers. No distributed locks. Just entities, messages, and guarantees.
 
 ---
 
-## How It Works
-
-### The Problem
+## The Problem
 
 Every distributed system eventually hits this:
 
@@ -86,157 +55,76 @@ T₃                                   UPDATE: $100 − $80 = $20     −$60
 Result: Balance is −$60. Both withdrawals succeed. Integrity violated.
 ```
 
-### The Solution
+## The Solution
 
-atomic-queues routes operations through per-entity queues. Same entity → same queue → sequential execution. Different entities → parallel queues → full throughput.
+atomic-queues routes operations through per-entity message logs. Same entity → same log → sequential execution. Different entities → parallel logs → full throughput. A shared executor pool dispatches messages via atomic Redis gates — no workers to spawn, no locks to contend.
 
 ```
                         ┌─────────────────────────────────────────────────┐
   Request A ─┐          │           Entity: account-42                    │
              │          │  ┌──────┐  ┌──────┐  ┌──────┐                  │
-  Request B ─┼─► Route ─┼─►│ Op 1 │─►│ Op 2 │─►│ Op 3 │─► [Worker] ──┐  │
-             │          │  └──────┘  └──────┘  └──────┘               │  │
-  Request C ─┘          │                    Sequential ◄─────────────┘  │
-                        └─────────────────────────────────────────────────┘
-
-                        ┌─────────────────────────────────────────────────┐
-  Request D ─┐          │           Entity: account-99                    │
-             │          │  ┌──────┐  ┌──────┐                            │
-  Request E ─┼─► Route ─┼─►│ Op 1 │─►│ Op 2 │─────────► [Worker] ──┐    │
-             │          │  └──────┘  └──────┘                       │    │
-  Request F ─┘          │                    Sequential ◄───────────┘    │
+  Request B ─┼─► Route ─┼─►│ Msg1 │─►│ Msg2 │─►│ Msg3 │─► [Executor] ─┐ │
+             │          │  └──────┘  └──────┘  └──────┘               │ │
+  Request C ─┘          │                     Sequential ◄────────────┘ │
                         └─────────────────────────────────────────────────┘
-
-                        ▲ These two queues run in PARALLEL across pods ▲
 ```
 
-**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.
-
 ---
 
 ## Installation
 
 ```bash
-npm install atomic-queues
+npm install atomic-queues ioredis
 ```
 
-BullMQ, ioredis, and `@nestjs/bullmq` are bundled — no extra installs needed.
+Optional peer dependencies:
 
-**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).
+```bash
+npm install @nestjs/cqrs          # for CQRS surface
+npm install zod zod-to-json-schema # for schema validation in the registry
+```
 
 ---
 
 ## Quick Start
 
-### 1. Configure the Module
+### Minimal setup
 
 ```typescript
 import { Module } from '@nestjs/common';
-import { CqrsModule } from '@nestjs/cqrs';
 import { AtomicQueuesModule } from 'atomic-queues';
 
 @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 {}
 ```
 
-> **Tip:** The `entities` config is optional. Without it, default naming applies: `{keyPrefix}:{entityType}:{entityId}:queue`.
-
-<details>
-<summary><strong>Async configuration (ConfigService)</strong></summary>
+### Define a command
 
 ```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],
-}),
-```
-
-</details>
-
-### 2. Define Commands
+import { EntityType, QueueEntityId } from 'atomic-queues';
 
-```typescript
-import { QueueEntity, QueueEntityId } from 'atomic-queues';
-
-@QueueEntity('account')
+@EntityType('account')
 export class WithdrawCommand {
   constructor(
     @QueueEntityId() public readonly accountId: string,
     public readonly amount: number,
   ) {}
 }
-
-@QueueEntity('account')
-export class DepositCommand {
-  constructor(
-    @QueueEntityId() public readonly accountId: string,
-    public readonly amount: number,
-  ) {}
-}
 ```
 
-### 3. Write Handlers (standard @nestjs/cqrs)
+### Enqueue it
 
 ```typescript
-import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
-
-@CommandHandler(WithdrawCommand)
-export class WithdrawHandler implements ICommandHandler<WithdrawCommand> {
-  constructor(private readonly repo: AccountRepository) {}
-
-  async execute({ accountId, amount }: WithdrawCommand) {
-    // SAFE: No race conditions. Sequential execution per account.
-    const account = await this.repo.findById(accountId);
-
-    if (account.balance < amount) {
-      throw new InsufficientFundsError(accountId, account.balance, amount);
-    }
-
-    account.balance -= amount;
-    await this.repo.save(account);
-  }
-}
-```
-
-### 4. Enqueue Jobs
-
-```typescript
-import { Injectable } from '@nestjs/common';
 import { QueueBus } from 'atomic-queues';
 
 @Injectable()
-export class AccountService {
+export class PaymentService {
   constructor(private readonly queueBus: QueueBus) {}
 
   async withdraw(accountId: string, amount: number) {
@@ -245,361 +133,244 @@ export class AccountService {
 }
 ```
 
-**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)
+That's it. The command is appended to `account:{accountId}`'s message log and executed sequentially by the shared executor pool.
 
 ---
 
-## Commands & Decorators
+## Three Surfaces
+
+atomic-queues exposes three interchangeable APIs. All three route to the same runtime. Pick whichever fits your mental model.
 
-### `@QueueEntity(entityType, entityIdProperty?)`
+### 1. Queue Surface
 
-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.
+The simplest path. Decorate commands, enqueue them.
 
 ```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,
-  ) {}
-}
+// Enqueue
+await queueBus.enqueue(new WithdrawCommand(accountId, 100));
 
-// 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,
-  ) {}
-}
+// Target a specific entity type
+await queueBus.forEntity('account').enqueue(new WithdrawCommand(accountId, 100));
+
+// Enqueue and wait for result
+const balance = await queueBus.enqueueAndWait(new GetBalanceQuery(accountId));
+
+// Bulk enqueue
+await queueBus.forEntity('account').enqueueBulk([charge1, charge2, charge3]);
 ```
 
-### `@QueueEntityId()`
+### 2. CQRS Surface
 
-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.
+For teams using `@nestjs/cqrs`. Commands and queries route through the actor runtime instead of executing inline.
 
 ```typescript
-@QueueEntity('account')
-export class TransferCommand {
+@JobCommand()
+@EntityType('account')
+export class WithdrawCommand {
   constructor(
-    @QueueEntityId() public readonly accountId: string,  // Routes to this account's queue
-    public readonly targetAccountId: string,
+    @QueueEntityId() public readonly accountId: string,
     public readonly amount: number,
   ) {}
 }
-```
 
-> **Entity ID resolution order:** `@QueueEntityId()` decorator > `@QueueEntity('type', 'prop')` second argument > `@WorkerProcessor({ defaultEntityId })` > `entities[type].defaultEntityId` in module config.
+@CommandHandler(WithdrawCommand)
+export class WithdrawHandler implements ICommandHandler<WithdrawCommand> {
+  async execute(cmd: WithdrawCommand) {
+    // business logic — guaranteed sequential per account
+  }
+}
+```
 
-### `@WorkerProcessor(options)`
+### 3. Actor Surface
 
-Optional. Define a processor class for custom job handling on top of CQRS auto-routing.
+For stateful entities. The class is the entity. Its methods are message handlers. Its fields are the state.
 
 ```typescript
-@WorkerProcessor({
-  entityType: 'account',
-  queueName: (id) => `account-${id}-queue`,
-  workerName: (id) => `account-${id}-worker`,
-  maxWorkersPerEntity: 1,
-  idleTimeoutSeconds: 15,
-})
+import { Actor, On } from 'atomic-queues';
+
+@Actor('account')
 @Injectable()
-export class AccountProcessor {
-  @JobHandler('special-audit')
-  async handleAudit(job: Job, entityId: string) { ... }
+export class AccountActor {
+  private balance = 0;
+
+  @On(DepositCommand)
+  async deposit(msg: DepositCommand) {
+    this.balance += msg.amount;
+    return this.balance;
+  }
+
+  @On(WithdrawCommand)
+  async withdraw(msg: WithdrawCommand) {
+    if (this.balance < msg.amount) throw new InsufficientFunds();
+    this.balance -= msg.amount;
+    return this.balance;
+  }
 }
-```
 
-### `@JobHandler(jobName)` / `@JobHandler('*')`
+// Usage
+await actorSystem.send('account', accountId, new DepositCommand(100));
+const balance = await actorSystem.sendAndWait('account', accountId, new GetBalanceQuery());
+```
 
-Custom job handlers on a `@WorkerProcessor`. The wildcard `'*'` catches anything not matched by a specific handler.
+Actor state persists in memory between messages and is automatically saved to Redis on idle eviction.
 
 ---
 
-## Configuration
+## Cross-Service Communication
+
+Enable the distributed registry and any service connected to the same Redis can send typed messages to any entity — no gRPC, no service mesh, no HTTP endpoints.
 
 ```typescript
+// Service B: defines and handles the entity
 AtomicQueuesModule.forRoot({
-  // ── Redis connection ──────────────────────────────────────
-  redis: {
-    host: 'redis',
-    port: 6379,
-    password: 'secret',       // optional
-  },
-
-  // ── 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
+  redis: { url: process.env.REDIS_URL },
+  registry: {
+    enabled: true,
+    serviceName: 'billing-service',
   },
+})
 
-  // ── 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',
-
-      workerConfig: {          // Override workerDefaults per entity
-        concurrency: 1,
-        lockDuration: 60000,
-      },
-    },
-  },
-});
+// Service A: sends to it (shared Redis, no code dependency on B)
+await queueBus.enqueue(new WithdrawCommand(accountId, 100));
 ```
 
----
+The registry validates at the call site: entity type exists, message is accepted, payload matches schema (optional). Errors are immediate and clear — not silent dead letters.
 
-## Distributed Worker Lifecycle
+### Schema Validation
 
-Workers in atomic-queues have a fully automated lifecycle, distributed across all pods with no leader election:
+Attach Zod schemas to message classes for compile-time and runtime safety:
 
-```
-  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      │
-                     └──────────────┘
+```typescript
+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;
+}
 ```
 
-### Hot Cache
+Enable `schemaValidation: true` in the registry config. Payload shape is validated against the JSON Schema representation before the message enters the log.
 
-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.
+### Codegen
 
-| 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 |
+Generate typed interfaces from the live registry:
 
-### SpawnQueueService
+```bash
+REDIS_URL=redis://localhost:6379 npx atomic-queues generate --ts --output ./generated/contracts.ts
+```
 
-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.
+Service A gets fully typed message interfaces without importing Service B's code. Also supports `--json-schema` and `--snapshot`.
 
 ---
 
-## Complete Example
-
-A banking service with withdrawals, deposits, and cross-account transfers:
+## Configuration
 
 ```typescript
-// ── Module ──────────────────────────────────────────────
-import { Module } from '@nestjs/common';
-import { CqrsModule } from '@nestjs/cqrs';
-import { AtomicQueuesModule } from 'atomic-queues';
+AtomicQueuesModule.forRoot({
+  redis: { host: 'localhost', port: 6379 },
 
-@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,
-        },
-      },
-    }),
-  ],
-  providers: [
-    AccountService,
-    WithdrawHandler,
-    DepositHandler,
-    TransferHandler,
-  ],
-})
-export class BankingModule {}
+  executor: {
+    poolSize: 1,          // concurrent executors per node
+    gateTTL: 30,          // seconds before gate expires (safety net)
+  },
 
-// ── Commands ────────────────────────────────────────────
-import { QueueEntity, QueueEntityId } from 'atomic-queues';
+  entities: {
+    account: {
+      defaultEntityId: 'accountId',
+      gateTTL: 60,
+      retry: { maxAttempts: 5, backoff: 'exponential', backoffDelay: 2000 },
+      actorIdleTimeout: 120000,
+      statePersistence: true,   // default: true
+    },
+  },
 
-@QueueEntity('account')
-export class WithdrawCommand {
-  constructor(
-    @QueueEntityId() public readonly accountId: string,
-    public readonly amount: number,
-    public readonly transactionId: string,
-  ) {}
-}
+  registry: {
+    enabled: false,             // enable for cross-service
+    serviceName: 'my-service',
+    schemaValidation: false,
+    heartbeatInterval: 10000,
+    registrationTTL: 30,
+  },
 
-@QueueEntity('account')
-export class DepositCommand {
-  constructor(
-    @QueueEntityId() public readonly accountId: string,
-    public readonly amount: number,
-    public readonly source: string,
-  ) {}
-}
+  keyPrefix: 'aq',
+  verbose: false,
+})
+```
 
-@QueueEntity('account')
-export class TransferCommand {
-  constructor(
-    @QueueEntityId() public readonly accountId: string,
-    public readonly toAccountId: string,
-    public readonly amount: number,
-  ) {}
-}
+---
 
-// ── Handlers ────────────────────────────────────────────
-import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
+## Architecture
 
-@CommandHandler(WithdrawCommand)
-export class WithdrawHandler implements ICommandHandler<WithdrawCommand> {
-  constructor(private readonly repo: AccountRepository) {}
+### How it works
 
-  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);
-  }
-}
+1. **Enqueue**: message is appended to a Redis list (`{prefix}:log:{entityType}:{entityId}`) and the entity is added to the ready set.
+2. **Tickle**: a pub/sub notification wakes the executor pool.
+3. **Schedule**: a Lua script atomically picks an entity from the ready set, acquires its dispatch gate (`SET NX EX`), and pops the next message.
+4. **Execute**: the handler runs (actor method, CQRS handler, or registered processor).
+5. **Complete**: gate is released, entity is re-added to the ready set if more messages remain.
 
-@CommandHandler(TransferCommand)
-export class TransferHandler implements ICommandHandler<TransferCommand> {
-  constructor(
-    private readonly repo: AccountRepository,
-    private readonly queueBus: QueueBus,
-  ) {}
+### Guarantees
 
-  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}`),
-    );
-  }
-}
+| 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) |
 
-// ── Controller ──────────────────────────────────────────
-import { Controller, Post, Body, Param } from '@nestjs/common';
-import { QueueBus } from 'atomic-queues';
+### What this does NOT guarantee
 
-@Controller('accounts')
-export class AccountController {
-  constructor(private readonly queueBus: QueueBus) {}
+**Exactly-once processing.** Like every distributed message system, handlers must be idempotent. If an executor dies mid-processing, the message retries on another node.
 
-  @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 };
-  }
+---
 
-  @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 };
-  }
-}
-```
+## Polyglot Clients
 
----
+Redis is the protocol. Any language with a Redis client can send messages to atomic-queues entities — three Redis commands:
 
-## Advanced: Custom Worker Processors
+```
+LPUSH  {prefix}:log:{entityType}:{entityId}  '<message JSON>'
+SADD   {prefix}:ready  {entityType}:{entityId}
+PUBLISH {prefix}:tickle  1
+```
 
-For cases where CQRS auto-routing isn't enough, define a `@WorkerProcessor` with explicit `@JobHandler` methods:
+See [WIRE-PROTOCOL.md](./WIRE-PROTOCOL.md) for the complete specification.
 
-```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
-  }
+---
 
-  @JobHandler('*')
-  async handleAll(job: Job, entityId: string) {
-    // Wildcard — catches everything not explicitly handled
-    // Falls back to CQRS routing automatically when not defined
-  }
-}
-```
+## Decorator Reference
 
-> **Priority order:** Explicit `@JobHandler` → CQRS auto-routing (`@JobCommand`/`@JobQuery`) → Wildcard handler
+| Decorator | Purpose |
+|---|---|
+| `@EntityType('type')` | Route a command/query to an entity type |
+| `@QueueEntityId()` | Mark the property holding the entity ID |
+| `@QueueEntity('type', 'prop')` | Combined entity type + ID |
+| `@JobCommand()` | Mark a command for CQRS auto-routing |
+| `@JobQuery()` | Mark a query for CQRS auto-routing |
+| `@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 |
 
 ---
 
-## Performance
+## Migrating from V1
 
-### Why it's fast
+V2 is a full rewrite of the internals. BullMQ is removed. Workers are removed. The public API is largely preserved.
 
-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.
+**What stays the same**: `@EntityType`, `@QueueEntityId`, `@QueueEntity`, `@JobCommand`, `@JobQuery`, `queueBus.enqueue()`, `queueBus.forEntity()`, `queueBus.enqueueAndWait()`. These work identically.
 
-### When to use what
+**What's removed**: `@WorkerProcessor`, `@JobHandler`, `@EntityScaler`, `@OnSpawnWorker`, `@OnTerminateWorker`, `@GetActiveEntities`, `@GetDesiredWorkerCount`, `.forProcessor()`. All worker and scaling concepts are gone.
 
-| Use case | Recommendation |
-|---|---|
-| 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) |
+**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.
 
 ---