atomic-queues 2.0.0 → 2.0.1

package/README.md

@@ -34,15 +34,21 @@
 
 ## What is atomic-queues?
 
-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.
+**A distributed virtual actor runtime for Node.js, built entirely on Redis primitives.**
 
-No BullMQ. No workers. No distributed locks. Just entities, messages, and guarantees.
+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.
+
+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.
+
+```
+npm install atomic-queues ioredis
+```
 
 ---
 
 ## 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
@@ -55,9 +61,13 @@ 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 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.
+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.
 
 ```
                         ┌─────────────────────────────────────────────────┐
@@ -67,48 +77,22 @@ atomic-queues routes operations through per-entity message logs. Same entity →
              │          │  └──────┘  └──────┘  └──────┘               │ │
   Request C ─┘          │                     Sequential ◄────────────┘ │
                         └─────────────────────────────────────────────────┘
-```
-
----
-
-## Installation
 
-```bash
-npm install atomic-queues ioredis
+  Meanwhile, account-99, order-7, user-abc — all execute
+  in parallel on the same cluster, completely independent.
 ```
 
-Optional peer dependencies:
-
-```bash
-npm install @nestjs/cqrs          # for CQRS surface
-npm install zod zod-to-json-schema # for schema validation in the registry
-```
+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.
 
 ---
 
-## Quick Start
-
-### Minimal setup
-
-```typescript
-import { Module } from '@nestjs/common';
-import { AtomicQueuesModule } from 'atomic-queues';
+## How It Works
 
-@Module({
-  imports: [
-    AtomicQueuesModule.forRoot({
-      redis: { host: 'localhost', port: 6379 },
-    }),
-  ],
-})
-export class AppModule {}
-```
+### Entities and messages
 
-### Define a command
+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
-import { EntityType, QueueEntityId } from 'atomic-queues';
-
 @EntityType('account')
 export class WithdrawCommand {
   constructor(
@@ -118,53 +102,38 @@ export class WithdrawCommand {
 }
 ```
 
-### Enqueue it
-
-```typescript
-import { QueueBus } from 'atomic-queues';
-
-@Injectable()
-export class PaymentService {
-  constructor(private readonly queueBus: QueueBus) {}
-
-  async withdraw(accountId: string, amount: number) {
-    await this.queueBus.enqueue(new WithdrawCommand(accountId, amount));
-  }
-}
-```
-
-That's it. The command is appended to `account:{accountId}`'s message log and executed sequentially by the shared executor pool.
-
----
-
-## Three Surfaces
+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.
 
-atomic-queues exposes three interchangeable APIs. All three route to the same runtime. Pick whichever fits your mental model.
+### Two levels of abstraction
 
-### 1. Queue Surface
+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.
 
-The simplest path. Decorate commands, enqueue them.
+**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.
 
 ```typescript
-// Enqueue
-await queueBus.enqueue(new WithdrawCommand(accountId, 100));
-
-// Target a specific entity type
-await queueBus.forEntity('account').enqueue(new WithdrawCommand(accountId, 100));
+@Actor('account')
+@Injectable()
+export class AccountActor {
+  private balance = 0;
 
-// Enqueue and wait for result
-const balance = await queueBus.enqueueAndWait(new GetBalanceQuery(accountId));
+  @On(DepositCommand)
+  async deposit(msg: DepositCommand) {
+    this.balance += msg.amount;
+    return this.balance;
+  }
 
-// Bulk enqueue
-await queueBus.forEntity('account').enqueueBulk([charge1, charge2, charge3]);
+  @On(WithdrawCommand)
+  async withdraw(msg: WithdrawCommand) {
+    if (this.balance < msg.amount) throw new InsufficientFunds();
+    this.balance -= msg.amount;
+    return this.balance;
+  }
+}
 ```
 
-### 2. CQRS Surface
-
-For teams using `@nestjs/cqrs`. Commands and queries route through the actor runtime instead of executing inline.
+**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
-@JobCommand()
 @EntityType('account')
 export class WithdrawCommand {
   constructor(
@@ -176,69 +145,120 @@ export class WithdrawCommand {
 @CommandHandler(WithdrawCommand)
 export class WithdrawHandler implements ICommandHandler<WithdrawCommand> {
   async execute(cmd: WithdrawCommand) {
-    // business logic — guaranteed sequential per account
+    // This runs sequentially per account — cluster-wide.
+    // No locks. No transactions. The dispatch engine guarantees it.
   }
 }
 ```
 
-### 3. Actor Surface
+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.
 
-For stateful entities. The class is the entity. Its methods are message handlers. Its fields are the state.
+### Enqueuing messages
 
 ```typescript
-import { Actor, On } from 'atomic-queues';
-
-@Actor('account')
-@Injectable()
-export class AccountActor {
-  private balance = 0;
+// Fire-and-forget
+await queueBus.enqueue(new WithdrawCommand(accountId, 100));
 
-  @On(DepositCommand)
-  async deposit(msg: DepositCommand) {
-    this.balance += msg.amount;
-    return this.balance;
-  }
+// Enqueue and block until result
+const balance = await queueBus.enqueueAndWait(new GetBalanceQuery(accountId));
 
-  @On(WithdrawCommand)
-  async withdraw(msg: WithdrawCommand) {
-    if (this.balance < msg.amount) throw new InsufficientFunds();
-    this.balance -= msg.amount;
-    return this.balance;
-  }
-}
+// Scoped to an entity type
+await queueBus.forEntity('account').enqueueBulk([charge1, charge2, charge3]);
 
-// Usage
+// Actor-style direct send
 await actorSystem.send('account', accountId, new DepositCommand(100));
 const balance = await actorSystem.sendAndWait('account', accountId, new GetBalanceQuery());
 ```
 
-Actor state persists in memory between messages and is automatically saved to Redis on idle eviction.
+---
+
+## The Dispatch Engine
+
+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.
+
+### Per-entity message logs
+
+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.
+
+### The dispatch gate
+
+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.
+
+### Atomic Lua scheduling
+
+A single Lua script runs atomically in Redis to perform the entire dispatch cycle:
+
+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
+
+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.
+
+### Shared executor pool
+
+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
 
-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.
+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.
+
+atomic-queues replaces all of that with Redis.
+
+### How it works
+
+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
-// Service B: defines and handles the entity
+// billing-service: defines and handles the entity
 AtomicQueuesModule.forRoot({
   redis: { url: process.env.REDIS_URL },
-  registry: {
-    enabled: true,
-    serviceName: 'billing-service',
-  },
+  registry: { enabled: true, serviceName: 'billing-service' },
 })
 
-// Service A: sends to it (shared Redis, no code dependency on B)
+// payments-service: sends to it (shared Redis, no code dependency on billing)
 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.
+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.
+
+### What this replaces
+
+Think about what you no longer need:
 
-### Schema Validation
+**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.
 
-Attach Zod schemas to message classes for compile-time and runtime safety:
+**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
 import { Schema } from 'atomic-queues';
@@ -255,9 +275,13 @@ export class WithdrawCommand {
 }
 ```
 
-Enable `schemaValidation: true` in the registry config. Payload shape is validated against the JSON Schema representation before the message enters the log.
+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.
 
-### Codegen
+### Entity co-ownership
+
+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:
 
@@ -265,7 +289,75 @@ Generate typed interfaces from the live registry:
 REDIS_URL=redis://localhost:6379 npx atomic-queues generate --ts --output ./generated/contracts.ts
 ```
 
-Service A gets fully typed message interfaces without importing Service B's code. Also supports `--json-schema` and `--snapshot`.
+Also supports `--json-schema` for language-agnostic schema export and `--snapshot` for full registry dumps.
+
+---
+
+## Redis *is* the Protocol
+
+This is the most important architectural decision in the project, and it has implications that go far beyond NestJS.
+
+The wire protocol is [fully documented](./WIRE-PROTOCOL.md), intentionally simple, and versioned with breaking-change semantics. Enqueuing a message is three Redis commands:
+
+```
+LPUSH  aq:log:account:a-1  '<message JSON>'
+SADD   aq:ready  account:a-1
+PUBLISH aq:tickle  1
+```
+
+**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.
+
+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.
+
+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.
+
+This opens architectures that are genuinely difficult to build otherwise:
+
+- **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.
+
+---
+
+## Quick Start
+
+```typescript
+import { Module } from '@nestjs/common';
+import { AtomicQueuesModule } from 'atomic-queues';
+
+@Module({
+  imports: [
+    AtomicQueuesModule.forRoot({
+      redis: { host: 'localhost', port: 6379 },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Define a command and enqueue it:
+
+```typescript
+@EntityType('account')
+export class WithdrawCommand {
+  constructor(
+    @QueueEntityId() public readonly accountId: string,
+    public readonly amount: number,
+  ) {}
+}
+
+@Injectable()
+export class PaymentService {
+  constructor(private readonly queueBus: QueueBus) {}
+
+  async withdraw(accountId: string, amount: number) {
+    await this.queueBus.enqueue(new WithdrawCommand(accountId, amount));
+  }
+}
+```
+
+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.
 
 ---
 
@@ -286,12 +378,12 @@ AtomicQueuesModule.forRoot({
       gateTTL: 60,
       retry: { maxAttempts: 5, backoff: 'exponential', backoffDelay: 2000 },
       actorIdleTimeout: 120000,
-      statePersistence: true,   // default: true
+      statePersistence: true,
     },
   },
 
   registry: {
-    enabled: false,             // enable for cross-service
+    enabled: false,
     serviceName: 'my-service',
     schemaValidation: false,
     heartbeatInterval: 10000,
@@ -303,45 +395,44 @@ AtomicQueuesModule.forRoot({
 })
 ```
 
----
-
-## Architecture
+Optional peer dependencies:
 
-### How it works
+```bash
+npm install @nestjs/cqrs          # for CQRS handler auto-wiring
+npm install zod zod-to-json-schema # for schema validation in the registry
+```
 
-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.
+---
 
-### Guarantees
+## Guarantees
 
 | Guarantee | Scope | Mechanism |
 |---|---|---|
-| FIFO per entity | Cluster-wide | Redis list (LPUSH/RPOP) |
-| Single-writer per entity | Cluster-wide | Gate key (SET NX EX) |
+| 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) |
 
 ### What this does NOT guarantee
 
-**Exactly-once processing.** Like every distributed message system, handlers must be idempotent. If an executor dies mid-processing, the message retries on another node.
+**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.
 
 ---
 
-## Polyglot Clients
-
-Redis is the protocol. Any language with a Redis client can send messages to atomic-queues entities — three Redis commands:
-
-```
-LPUSH  {prefix}:log:{entityType}:{entityId}  '<message JSON>'
-SADD   {prefix}:ready  {entityType}:{entityId}
-PUBLISH {prefix}:tickle  1
-```
+## How It Compares
 
-See [WIRE-PROTOCOL.md](./WIRE-PROTOCOL.md) for the complete specification.
+| 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 |
 
 ---
 
@@ -349,11 +440,9 @@ See [WIRE-PROTOCOL.md](./WIRE-PROTOCOL.md) for the complete specification.
 
 | Decorator | Purpose |
 |---|---|
-| `@EntityType('type')` | Route a command/query to an entity type |
+| `@EntityType('type')` | Route a message 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 |
@@ -364,7 +453,7 @@ See [WIRE-PROTOCOL.md](./WIRE-PROTOCOL.md) for the complete specification.
 
 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`, `@JobCommand`, `@JobQuery`, `queueBus.enqueue()`, `queueBus.forEntity()`, `queueBus.enqueueAndWait()`. These work identically.
+**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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atomic-queues",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Distributed virtual actor runtime for Node.js — sequential per entity, parallel across entities, zero contention",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",