From 8d062b4800e70deec04f823024073da5aa63170d Mon Sep 17 00:00:00 2001
From: nyx <nyx@eachpath.local>
Date: Fri, 6 Nov 2026 15:42:48 +0100
Subject: [PATCH] lemniscate: NATS vocabulary label map for inputs/outputs,
 open naming-convention flag

---
 architecture/lemniscate.md | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/architecture/lemniscate.md b/architecture/lemniscate.md
index bfa2caa..e85dfb0 100644
--- a/architecture/lemniscate.md
+++ b/architecture/lemniscate.md
@@ -25,6 +25,30 @@ Figure-eight with two lobes and two crossings:
      Gate Feedback            Action Call (tool/actuator)
 ```
 
+### NATS vocabulary (label map)
+
+| Lemniscate label | NATS role | Transport | Delivery guarantee |
+|---|---|---|---|
+| sensor `pub <sensor.subject>` | publisher | core NATS | fire-and-forget: only subscribers open at publish time get a copy; late subscribers get nothing |
+| `gate.summary`, `gate.decision` | subject (fan-in at L1, fan-out to gate layer) | core NATS | ephemeral, regenerated every pulse; nothing survives the cycle |
+| L1 (LLM) | subscriber on `gate.summary`, publisher on `gate.decision` | core NATS client | a swappable bus client, any language |
+| `action.call.<target>` | stream (JetStream) | durable | at-least-once delivery, replayable |
+| actuator:`<t>` | own JetStream consumer on its subject | durable | tracks its own position; a dead actuator stalls no one |
+| `action.result` | stream (JetStream) | durable | causality: `event_uuid -> cycle_uuid -> decision_uuid` |
+| client:`<name>` | own durable consumer on `zone.state.>` / `action.result.>` | durable | replay-on-wake: reconnect and read what it missed |
+
+Rules in NATS words: fan-out is the subject matcher, not code (wildcard
+`*` = one token, `>` = one or more). Fan-in means many publishers onto
+one subject; each consumer position is independent, consumers never
+share state or corrupt each other. Idempotency is enforced by us, via
+dedupe on `decision_uuid`/`cycle_uuid`, because JetStream guarantees
+*at-least-once*, never *exactly-once*.
+
+Subject naming (open): the engine above uses short subjects
+(`gate.summary`, `action.call.<target>`). Our live bus streams use
+`nimmerverse.register.>` / `nimmerverse.cycle.>`. Before any engine
+traffic flows, pick ONE naming convention and map it here.
+
 ### Bus transport (NATS / JetStream)
 
 The engine is host-agnostic: it never speaks to a model or an actuator directly,
@@ -173,4 +197,4 @@ while elapsed >= interval:
 - Register/catalog: sensors, gates, actuators, clients, `drives`. Catalog entry declares the class path; runtime imports an explicit registry and fails loud on a missing class.
 - Clients hold own durable consumers on `zone.state.>` and `action.result.>` (replay-on-wake).
 
-Version: 0.11 | Updated: 2026-11-04
+Version: 0.12 | Updated: 2026-11-06