feat: Revise architecture documentation to enhance clarity and detail on LNMP protocol structure and data flow

Author: Madraka

spec/architecture-and-flow.md

@@ -1,129 +1,148 @@
-# LNMP Architecture & Flow Visualization
+# LNMP Architecture & Flow: The Digital Organism
 
-This document visualizes the "DNA-like" structure of the LNMP protocol, showing how Semantic Field Engine (SFE), Registry, Codec, and Transport layers synchronize to enable Agent-to-Agent (A2A) and Model-to-Model (M2M) communication.
+This document provides a comprehensive, end-to-end visualization of the LNMP protocol. It maps the technical modules to "biological" systems to illustrate how LNMP functions not just as a data format, but as a living language for AI agents.
 
-## The LNMP Centipede (Protocol Stack)
+## 1. The Anatomy of LNMP (Module Map)
 
-The protocol operates like a biological organism where each segment has a specific function, connected by a central nervous system (The Core).
+Each crate in the ecosystem serves a critical physiological function in the digital organism.
 
 ```mermaid
 graph TD
-    subgraph "Agent A (Brain)"
-        A_Ctx[Context / Intent]
-        A_SFE[SFE: Semantic Field Engine]
+    %% Brain & Intent
+    subgraph "Cortex (Higher Function)"
+        App[Application Logic]
+        SFE[lnmp-sfe: Semantic Field Engine]
+        App -->|Intent/Context| SFE
     end
 
-    subgraph "Protocol Stack (The DNA Spine)"
-        Core[LNMP Core: Universal Types & Registry]
-        Codec[LNMP Codec: Binary/Chemical Encoding]
-        Trans[LNMP Transport: Neural/Network Pathways]
+    %% Core System
+    subgraph "DNA & Nervous System (The Core)"
+        Core[lnmp-core: Types & Registry]
+        Codec[lnmp-codec: Encoding & Rules]
     end
 
-    subgraph "Agent B (Brain)"
-        B_SFE[SFE: Semantic Field Engine]
-        B_Ctx[Action / Understanding]
+    %% Body & Capabilities
+    subgraph "Physiology (Capabilities)"
+        Spatial[lnmp-spatial: Proprioception/Space]
+        Emb[lnmp-embedding: Memory/Vector]
+        Quant[lnmp-quant: Efficiency/Compression]
+    end
+
+    %% Protection & Transport
+    subgraph "Immune & Circulatory System"
+        Env[lnmp-envelope: Cell Wall & Identity]
+        Net[lnmp-net: Networking/Flow]
+        Net -->|TCP/QUIC| Ext[External World]
     end
 
     %% Connections
-    A_Ctx -->|Contextualizes| A_SFE
-    A_SFE -->|Maps to FIDs| Core
-    Core -->|Serializes| Codec
-    Codec -->|Encapsulates| Trans
+    SFE -->|Maps Meaning to FIDs| Core
+    Core -->|Defines Structure| Codec
     
-    Trans <==>|Bi-Directional Flow| Trans
+    Codec -->|Serializes| Env
+    Env -->|Encapsulates| Net
     
-    Trans -->|Decapsulates| Codec
-    Codec -->|Deserializes| Core
-    Core -->|Resolves FIDs| B_SFE
-    B_SFE -->|Understands| B_Ctx
-
-    %% Styling
-    style Core fill:#f96,stroke:#333
-    style Codec fill:#69f,stroke:#333
-    style Trans fill:#9f9,stroke:#333
+    Spatial -->|Extends| Core
+    Emb -->|Extends| Core
+    Quant -->|Optimizes| Emb
 ```
 
-## The Connectivity DNA Helix (E2E Flow)
+### 🧬 Structural Meaning
+*   **lnmp-core (The DNA):** The immutable truths. FIDs (Field IDs) are the genetic codons (A, C, G, T) that define meaning efficiently.
+*   **lnmp-sfe (The Brain):** Translates abstract "thoughts" (User Intent) into genetic instructions (FIDs).
+*   **lnmp-envelope (The Cell Wall):** Protects the payload. Contains the Identity (Source), Timestamp, and Trace ID. It ensures the "cell" is distinct and traceable.
+*   **lnmp-quant (Metabolism):** Optimizes energy usage by compressing heavy vector data (Embeddings) up to 32x, allowing the organism to "think" faster and lighter.
+*   **lnmp-spatial (Proprioception):** Gives the agent a sense of "self" in physical or virtual space.
+
+---
+
+## 2. The Cycle of Life: E2E Data Flow
+
+This diagram illustrates the complete journey of a "Thought" becoming an "Action" across the network.
+
+### Stage A: Conception (Intent Formation)
+*   **Source:** Agent A wants to say *"Move to coordinates (10, 20) quickly."*
+*   **SFE:** Maps concepts -> FIDs: `Action=Move`, `Pos=[10,20]`, `Urgency=High`.
+
+### Stage B: DNA Transcription (Encoding)
+*   **Core:** Validates values against the Registry (e.g., `Pos` must be `:fa` FloatArray).
+*   **Codec:** Transcribes these values into compact Binary LNMP (The "RNA" strand).
+
+### Stage C: Cellular Transport (Encapsulation)
+*   **Envelope:** Wraps the Binary payload. Adds headers: `Source: AgentA`, `TraceID: xyz-123`, `Time: 1734438000`.
+*   **Net:** Transmits the envelope over the wire (Bloodstream).
 
-This sequence diagram illustrates the "Double Helix" interaction between two agents. The strands are connected by protocol bonds (Negotiation, Sync, Data).
+### Stage D: Reception & Perception
+*   **Agent B** receives the pulse.
+*   **Envelope:** Verifies Identity (Source). "This is safe."
+*   **Codec:** Decodes binary back to structured data.
+*   **SFE:** "Feeling" the data. Resolves FIDs back to concepts.
+*   **Spatial:** Updates internal world model. "Agent A is moving."
 
 ```mermaid
 sequenceDiagram
-    participant A as Agent A (Client)
-    participant B as Agent B (Service)
-    
-    Note over A,B: Phase 1: Recognition (Discovery & Handshake)
-    
-    A->>B: 🟡 Hello (Protocol v0.5)
-    B-->>A: 🟢 Welcome (Capabilities + Registry v1.2)
-    
-    rect rgb(20, 20, 30)
-        Note left of A: DNA Bonding: Schema Alignment
-        A->>A: Check Registry Sync
-        alt Registry Mismatch
-            A->>B: 🔴 RequestRegistryDelta(v1.0 -> v1.2)
-            B-->>A: 🔵 RegistryDelta (New FIDs defined)
-            A->>A: Apply Delta & Compile
-        end
-    end
-    
-    A->>B: 🟡 Ready (Schema Negotiated)
-    
-    Note over A,B: Phase 2: Synthesis (Data Exchange)
+    participant Mind as 🧠 Agent Mind
+    participant SFE as 🔮 SFE (Translator)
+    participant Core as 🧬 Core/Codec
+    participant Env as 🛡️ Envelope
+    participant Net as 📡 Network
+
+    %% Sending
+    Note over Mind, Net: 1. OUTBOUND FLOW (Expression)
+    Mind->>SFE: Intent: "Move(10, 20)"
+    SFE->>Core: Lookup FIDs (Move=100, x=256...)
+    Core->>Core: Validate Types (:fa, :s)
+    Core->>Env: Payload (Binary DNA)
+    Env->>Env: Seal (Add Trace/Source)
+    Env->>Net: Dispatch (Packet)
+
+    %% Network Transit
+    Net-->>Net: ⚡ Transmission ⚡
+
+    %% Receiving
+    Note over Mind, Net: 2. INBOUND FLOW (Perception)
+    Net->>Env: Receive (Packet)
+    Env->>Env: Verify Identity
+    Env->>Core: Unwrap Payload
+    Core->>SFE: Decode DNA to FIDs
+    SFE->>Mind: Semantic Concept: "Target Moving"
     
-    loop Stream / Bi-Directional
-        A->>B: 📦 [Msg: Prompt] + [Ctx: Temperature=0.7] (FIDs: 10, 768)
-        
-        rect rgb(40, 40, 50)
-            Note right of B: Semantic Processing
-            B->>B: Decode -> Resolve FIDs -> Inference
-        end
-        
-        B-->>A: 📦 [Msg: Response] + [Meta: Complexity=0.9] (FIDs: 11, 41)
-        
-        opt Spatial Context (Multimodal)
-            A->>B: 🧊 [Spatial: Position + Vector] (F256, F512)
-            B-->>A: 🧊 [Spatial: New Coordinates]
-        end
+    opt Spatial Reflex
+        Mind->>Mind: Update Spatial Index
     end
-    
-    Note over A,B: Phase 3: Termination
-    
-    A->>B: 🔴 Close Session
-    B-->>A: 🔴 Ack
 ```
 
-## Module Interactions (The Organism)
+---
+
+## 3. The "Centipede" Topology (Multi-Agent Harmony)
 
-How the Rust crates interact internally to produce the "Life Logic".
+LNMP allows multiple modules to connect like segments of a centipede, moving in unison.
 
 ```mermaid
-classDiagram
-    class Application {
-        +Context
-        +Intent
-    }
-    
-    class LnmpSFE {
-        +ConceptMapper
-        +ContextAnalyst
-        +fid_lookup()
-    }
-    
-    class LnmpCore {
-        +FidRegistry
-        +LnmpRecord
-        +LnmpValue
-    }
-    
-    class LnmpCodec {
-        +SchemaNegotiator
-        +BinaryEncoder
-        +BinaryDecoder
-    }
-    
-    Application --> LnmpSFE : Uses
-    LnmpSFE --> LnmpCore : Definitions
-    LnmpSFE --> LnmpCodec : Serializes
-    LnmpCore <|-- LnmpCodec : Implements Types
+graph LR
+    subgraph "Agent Cluster"
+        A[Agent Node] <-->|Sync| B[Agent Node]
+        B <-->|Sync| C[Agent Node]
+        C <-->|Sync| A
+    end
+
+    subgraph "Shared Reality (Registry)"
+        Reg((Registry Source))
+    end
+
+    A -.->|Pull Schema| Reg
+    B -.->|Pull Schema| Reg
+    C -.->|Pull Schema| Reg
+
+    style Reg fill:#f96,stroke:#333,stroke-width:4px
 ```
+
+*   **Synchronization:** Unlike strict APIs (Rest/JSON), LNMP agents share a "genetic link" (The Registry). If the Registry evolves (new FIDs), all agents evolve their understanding instantly without breaking the connection.
+*   **M2M (Machine-to-Machine):** High-speed, low-latency binary stream.
+*   **A2A (Agent-to-Agent):** High-context, semantic meaning exchange.
+
+## 4. Why This Structure?
+
+1.  **Semantic Density:** By separating the *definition* (Registry) from the *transmission* (Binary), we achieve maximum information density. We don't send keys like `"temperature"`, we send `768`.
+2.  **Evolutionary Safety:** Old agents ignore new FIDs (Junk DNA), while new agents utilize them. This allows the system to evolve organically without "breaking changes".
+3.  **Universal Grounding:** Through `lnmp-spatial` and `lnmp-core`, all agents agree on fundamental truths (Time, Space, Identity), preventing hallucinations in multi-agent collaboration.