novox/hq
3
0
Fork 0
Code Issues 3 Pull Requests 5 Releases Wiki Activity

Designs 25 and 29 disagreed about the subject space; implementing found it

Browse Source 
29 put a module's events and tools in one namespace, 25 kept mesh.events.*
and mesh.tools.*. One namespace is right — a module's authority over its own
name becomes a single pattern the server enforces — but it needs a kind
token, because a stream is a subject filter and mesh.mod.*.> would persist
every tool call in the mesh. Tools stay on core NATS for the reason 25
already gives.

So: mesh.mod.<module>.event.<name>, .tool.<name>, and seats the same shape.
This commit is contained in:
jschoubben
2026-09-26 21:02:18 +02:00
parent 3f9b316015
commit 78a2274baf
2 changed files with 24 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
03-DESIGN/01-to-be/29-what-a-module-declares.md
+12 -4
View File
@@ -34,11 +34,19 @@ the catalogue, and the mesh would have hundreds of copies of a decision it made
| declared | derived |
|---|---|
| `emits: order.placed` | publish on `mesh.mod.<module>.order.placed` |
| `consumes: billing.order.placed` | durable consumer on `mesh.mod.billing.order.placed` |
| `emits: order.placed` | publish on `mesh.mod.<module>.event.order.placed` |
| `consumes: billing.order.placed` | durable consumer on `mesh.mod.billing.event.order.placed` |
| `serves: status` | queue-group subscription on `mesh.mod.<module>.tool.status` |
| seat `telegram-sender`, `accepts: send` | work-queue consumer on `mesh.seat.telegram-sender.send` |
| `uses: telegram-sender` | publish on that seat's `accepts` subjects, and nothing else |
| seat `telegram-sender`, `accepts: send` | work-queue consumer on `mesh.seat.telegram-sender.accept.send` |
| `uses: telegram-sender` | publish on that seat's `accept` subjects, and nothing else |
**The `event` / `tool` / `accept` token is load-bearing, not decoration.** Revision, found while
defining the streams: a stream is defined by a subject filter, so a namespace holding both a
module's events and its tool calls cannot be filtered into an events stream without capturing
every tool invocation in the mesh — and a tool call must never be persisted
([design 25](25-the-bus-on-nats.md) §3 keeps tools on core NATS, where a lost call is a timeout the
caller already handles). The kind token is what makes `mesh.mod.*.event.>` a safe filter. The
first draft of this table had no token, which reads better and cannot be implemented.
**The test this must pass: the manifest survives the wire changing.** Reorganise the subject space
and every manifest in the catalogue is still correct. That is the property