EchoMQ 2.0 —
the protocol break

The v1 wire carries two structural inheritances that cap it on any placement-aware store — wherever a key's {…} hashtag decides its placement. First, the undeclared-keys flaw: roughly half of the 50 inherited Lua scripts (about 24–26, pattern-dependent) build per-job keys inside the script (local jobKey = keyPrefix .. jobId — moveToActive-11.lua:148) and never declare them in KEYS[] — outside the engine scripting contract (Valkey's own guidance: every key a script accesses arrives as an input key argument). Second, the unplaced keyspace: EchoMQ.Keys interpolates the queue name verbatim — no hashtags, so nothing for the threads to balance on. Containing both under compatibility has a proven ceiling; resolving both means breaking the wire. So the wire breaks — once, versioned, at the first rung.

Read this chapter first if you follow the build into groups (E4), batches (E5), lifecycle controls (E6), or the cache (E7) — each rides the v2 protocol this break establishes. The interactive below shows the fork directly: the same queue's keys on the v1 line and under the 2.0 protocol emq.1 ships.

Three orientation dives take the break's big ideas in turn, before the granular modules: the keyspace EchoMQ owns once it stops speaking emq:, the versioned fence and migration path that make one break safe, and the conformance probes that replace compatibility as the standing check.

The orientation above is the front door; the depth is four modules and a workshop, each a hub with three dives, re-derived from the rewritten rung's deliverables — as each is authored, its card here links through.

The break is one rung with one mechanism: own the keyspace, declare the keys, version the wire. emq.1 ships the key builders that write emq:{q}:wait, emq:{q}:active, emq:{q}:<jobId> — the per-queue hashtag inserted by the core, never by the caller — and a script set in which every key a script touches is listed in KEYS[] before the script runs. The v1 line concatenates per-job keys inside the script (local jobKey = keyPrefix .. jobId, moveToActive-11.lua:148), outside the engine scripting contract — Valkey's guidance: every key a script accesses arrives in KEYS[]. With every key declared and placed by its {q} hashtag, each call's key set is slot-local and known before it runs. meta.version records echomq:2.0.0; a two-way boot fence refuses cross-version contact; the migration path moves a v1 deployment over once, deliberately.

E4–E8 each build on the 2.0 wire emq.1 ships — declared-keys scripts on the owned, placed keyspace. They are specified and on the way; each teaches from its rung's spec until the rung ships, then is re-grounded in the real modules.