From ed66b16821840bbb660132e309ebaac71a9f033d Mon Sep 17 00:00:00 2001
From: dullfig <dan.u@grmcompany.com>
Date: Sun, 4 Jan 2026 23:33:46 -0800
Subject: [PATCH] fixing docs

---
 docs/core-principles-v2.0.md |  6 ++++++
 docs/message-pump.md         | 40 ++++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/docs/core-principles-v2.0.md b/docs/core-principles-v2.0.md
index e7b6b65..ba89e75 100644
--- a/docs/core-principles-v2.0.md
+++ b/docs/core-principles-v2.0.md
@@ -89,4 +89,10 @@ These principles are the single canonical source of truth for the project. All d
 - Caller idles naturally; wakeup messages bubble back via standard tracing.
 - Enables recurrent tasks (e.g., periodic monitoring) without blocking or external schedulers.
 
+## Bounded Stateful Listeners
+- Pure tools remain stateless.
+- Stateful capabilities (e.g., calculator memory, game state) store data per thread path UUID.
+- Ensures isolation across conversations, automatic cleanup on idle, and minimal mutable state.
+- Handler closes over or receives UUID for access — still oblivious to readable path.
+
 These principles are now locked. All existing docs will be updated to match this file exactly. Future changes require explicit discussion and amendment here first.
\ No newline at end of file
diff --git a/docs/message-pump.md b/docs/message-pump.md
index 4d4bb83..74e8ecb 100644
--- a/docs/message-pump.md
+++ b/docs/message-pump.md
@@ -2,6 +2,46 @@
 
 The AgentServer message pump processes individual messages through a single, linear, attack-resistant pipeline. The outer dispatcher runs a continuous async loop, draining per-thread message buffers (queues) until empty — enabling persistent, branched reasoning without artificial limits.
 
+```mermaid
+flowchart TD
+    subgraph Ingress
+        A[Raw Bytes] --> B[Repair + C14N]
+        B --> C[Enqueue to Thread Queue]
+    end
+
+    subgraph DispatcherLoop
+        D[Dequeue Next Message] --> E{Envelope Valid?}
+        E -->|No| F[Discard / System Error]
+        E -->|Yes| G{Payload Namespace?}
+        G -->|Meta| H["Core Handler<br>(raw payload)"]
+        G -->|Normal| I[Validate Payload<br>vs Cached XSD]
+        I -->|Fail| F
+        I -->|Pass| J["Deserialize to<br>@xmlify Dataclass"]
+        J --> K["Call Handler<br>(typed instance → bytes)"]
+        H --> L["Wrap bytes in<br>&ltdummy&gt&lt/dummy&gt"]
+        K --> L
+    end
+
+    subgraph Response
+        L --> M[Repair + Extract<br>Multi-Payloads]
+        M --> N{Extracted Payloads?}
+        N -->|0| O["Optional: Inject<br>&ltagent-error&gt or Idle"]
+        N -->|1 or more| P[For Each Payload:]
+        P --> Q[Determine Target Listener]
+        Q --> R["Append Target Name<br>to Current Path<br>(new thread ID)"]
+        R --> S["Inject <from><br>(listener name)"]
+        S --> T["Enqueue New Message(s)<br>to Deepened Path(s)<br>(parallel if multi)"]
+        T --> U[On Response Bubbling:<br>Pop Last Segment<br>Route to Parent Path]
+    end
+
+    C --> DispatcherLoop
+    DispatcherLoop --> Response
+    Response --> DispatcherLoop
+    style Ingress fill:#f0f8ff
+    style DispatcherLoop fill:#f0fff0
+    style Response fill:#fff0f0
+```
+
 ```mermaid
 flowchart TD
     subgraph MessagePump