feat(synapse): add soul version increment and encoding state propagation

Wire monotonic soul version increment into CognitiveSoulService:
- saveAgentSoul: read current version from INSULA, increment, set on
  rebuilt soul, push to SpectorMemory.setSoulVersion()
- saveUserSoul: same pattern with full 8-arg UserSoul constructor
- loadAgentSoul: propagate loaded version to SpectorMemory

Update all AgentSoul construction sites in synapse module:
- AgentController, ChatService, DynamicGraphBuilder, UpdateAgentSoulTool

Wire soul version restoration at startup in UserMemoryRegistry
alongside salience profile loading from INSULA.

Refs #502

Co-authored-by: Bharat Joshi <bharatjoshi@spectrayan.com>

Author: forgespectrayan

synapse/spector-synapse/src/main/java/com/spectrayan/spector/synapse/agent/AgentController.java

@@ -84,6 +84,11 @@ public ResponseEntity<AgentSoul> updateSoul(@RequestBody AgentSoul soul) {
                 .communicationStyle(soul.communicationStyle())
                 .model(soul.model())
                 .tools(soul.tools())
+                .expertiseEmbedding(soul.expertiseEmbedding())
+                .purposeEmbedding(soul.purposeEmbedding())
+                .soulVersion(soul.soulVersion())
+                .createdAt(soul.createdAt())
+                .updatedAt(soul.updatedAt())
                 .build();
         soulService.saveAgentSoul(updated);
         return ResponseEntity.ok(updated);
@@ -141,6 +146,11 @@ public ResponseEntity<AgentSoul> updateAgent(@PathVariable String id, @RequestBo
                 .communicationStyle(soul.communicationStyle())
                 .model(soul.model())
                 .tools(soul.tools())
+                .expertiseEmbedding(soul.expertiseEmbedding())
+                .purposeEmbedding(soul.purposeEmbedding())
+                .soulVersion(soul.soulVersion())
+                .createdAt(soul.createdAt())
+                .updatedAt(soul.updatedAt())
                 .build();
         soulService.saveAgentSoul(updated);
         return ResponseEntity.ok(updated);

synapse/spector-synapse/src/main/java/com/spectrayan/spector/synapse/agent/chat/service/ChatService.java

@@ -213,6 +213,9 @@ private AgentChatResponse processChat(
                 .personality(soul != null ? soul.personality() : null)
                 .model(model != null ? model : DEFAULT_MODEL)
                 .tools(soul != null ? soul.tools() : List.of())
+                .expertiseEmbedding(soul != null ? soul.expertiseEmbedding() : null)
+                .purposeEmbedding(soul != null ? soul.purposeEmbedding() : null)
+                .soulVersion(soul != null ? soul.soulVersion() : (short) 1)
                 .createdAt(soul != null ? soul.createdAt() : java.time.Instant.now())
                 .updatedAt(soul != null ? soul.updatedAt() : java.time.Instant.now());
 

synapse/spector-synapse/src/main/java/com/spectrayan/spector/synapse/agent/graph/DynamicGraphBuilder.java

@@ -224,6 +224,7 @@ private NodeAction<CognitiveState> createAgentNode(String nodeName,
                                 .name(agentSpec.name() != null ? agentSpec.name() : agentId)
                                 .systemPrompt(agentSpec.systemPrompt())
                                 .model(agentSpec.llm() != null ? agentSpec.llm().model() : "qwen3.5:latest")
+                                .soulVersion((short) 1)
                                 .build();
                     }
                     // Fall back to active default soul

synapse/spector-synapse/src/main/java/com/spectrayan/spector/synapse/agent/service/CognitiveSoulService.java

@@ -56,6 +56,9 @@ public class CognitiveSoulService {
             .communicationStyle("professional")
             .model("qwen3.5:latest")
             .tools(List.of())
+            .soulVersion((short) 1)
+            .createdAt(java.time.Instant.now())
+            .updatedAt(java.time.Instant.now())
             .build();
 
     private final UserMemoryRegistry userMemoryRegistry;
@@ -85,6 +88,7 @@ public Optional<AgentSoul> loadAgentSoul(String id) {
                 .flatMap(bytes -> fromJsonBytes(bytes, InsulaSelfModel.class))
                 .map(model -> {
                     if (model.soul() instanceof AgentSoul agentSoul) {
+                        memory.setSoulVersion(agentSoul.soulVersion());
                         return agentSoul;
                     }
                     return null;
@@ -112,13 +116,48 @@ public void saveAgentSoul(AgentSoul soul) {
             return;
         }
 
-        InsulaSelfModel selfModel = new InsulaSelfModel("AGENT", soul, null, Map.of());
-        byte[] bytes = toJsonBytes(selfModel);
+        short nextVersion = 1;
         var insula = memory.admin().insularCortex();
+        if (insula != null) {
+            nextVersion = insula.get()
+                .flatMap(bytes -> fromJsonBytes(bytes, InsulaSelfModel.class))
+                .map(model -> {
+                    if (model.soul() instanceof AgentSoul as) {
+                        return (short)(as.soulVersion() + 1);
+                    }
+                    return (short)1;
+                })
+                .orElse((short)1);
+        }
+
+        AgentSoul savedSoul = AgentSoul.builder()
+                .id(soul.id())
+                .name(soul.name())
+                .description(soul.description())
+                .systemPrompt(soul.systemPrompt())
+                .purpose(soul.purpose())
+                .personality(soul.personality())
+                .expertiseDomains(soul.expertiseDomains())
+                .coreValues(soul.coreValues())
+                .ethicalGuardrails(soul.ethicalGuardrails())
+                .emotionalBaseline(soul.emotionalBaseline())
+                .communicationStyle(soul.communicationStyle())
+                .model(soul.model())
+                .tools(soul.tools())
+                .expertiseEmbedding(soul.expertiseEmbedding())
+                .purposeEmbedding(soul.purposeEmbedding())
+                .soulVersion(nextVersion)
+                .createdAt(soul.createdAt() != null ? soul.createdAt() : java.time.Instant.now())
+                .updatedAt(java.time.Instant.now())
+                .build();
+
+        InsulaSelfModel selfModel = new InsulaSelfModel("AGENT", savedSoul, null, Map.of());
+        byte[] bytes = toJsonBytes(selfModel);
         if (bytes != null && insula != null) {
             insula.put(bytes);
         }
-        log.info("[CognitiveSoul] Saved agent soul '{}' in INSULA", soul.name());
+        memory.setSoulVersion(nextVersion);
+        log.info("[CognitiveSoul] Saved agent soul '{}' v{} in INSULA", soul.name(), nextVersion);
     }
 
     /**
@@ -171,18 +210,39 @@ public void saveUserSoul(PersonaContext persona) {
             return;
         }
 
-        UserSoul userSoul = new UserSoul(nsId, "User", "User Persona", persona, persona.aboutEmbedding());
+        short nextVersion = 1;
+        java.time.Instant createdAt = java.time.Instant.now();
+        var insula = memory.admin().insularCortex();
+        if (insula != null) {
+            var existingOpt = insula.get()
+                .flatMap(bytes -> fromJsonBytes(bytes, InsulaSelfModel.class))
+                .map(model -> {
+                    if (model.soul() instanceof UserSoul us) {
+                        return us;
+                    }
+                    return null;
+                });
+            if (existingOpt.isPresent()) {
+                UserSoul us = existingOpt.get();
+                nextVersion = (short)(us.soulVersion() + 1);
+                if (us.createdAt() != null) {
+                    createdAt = us.createdAt();
+                }
+            }
+        }
+
+        UserSoul userSoul = new UserSoul(nsId, "User", "User Persona", persona, persona.aboutEmbedding(), nextVersion, createdAt, java.time.Instant.now());
         InsulaSelfModel selfModel = new InsulaSelfModel("USER", userSoul, salienceProvider.effectiveProfile(), Map.of());
 
         byte[] bytes = toJsonBytes(selfModel);
-        var insula = memory.admin().insularCortex();
         if (bytes != null && insula != null) {
             insula.put(bytes);
         }
+        memory.setSoulVersion(nextVersion);
 
         // Propagate to salience provider
         salienceProvider.updateUserPersona(persona);
-        log.info("[CognitiveSoul] Saved user persona context to INSULA — salience profile updated");
+        log.info("[CognitiveSoul] Saved user persona v{} to INSULA — salience profile updated", nextVersion);
     }
 
     /** Get the current active agent soul, or a default fallback. */
@@ -214,7 +274,11 @@ public AgentSoul patchAgentSoul(Map<String, Object> updates) {
                 .personality(updates.containsKey("personality") ? (String) updates.get("personality") : current.personality())
                 .emotionalBaseline(updates.containsKey("emotionalBaseline") ? parseEmotionalBaseline(updates.get("emotionalBaseline")) : current.emotionalBaseline())
                 .communicationStyle(updates.containsKey("communicationStyle") ? (String) updates.get("communicationStyle") : current.communicationStyle())
-                .model(updates.containsKey("model") ? (String) updates.get("model") : current.model());
+                .model(updates.containsKey("model") ? (String) updates.get("model") : current.model())
+                .expertiseEmbedding(current.expertiseEmbedding())
+                .purposeEmbedding(current.purposeEmbedding())
+                .soulVersion(current.soulVersion())
+                .createdAt(current.createdAt());
 
         if (updates.containsKey("expertiseDomains")) {
             builder.expertiseDomains((List<String>) updates.get("expertiseDomains"));

synapse/spector-synapse/src/main/java/com/spectrayan/spector/synapse/agent/tools/UpdateAgentSoulTool.java

@@ -131,6 +131,9 @@ private String executeInternal(Map<String, Object> arguments) throws Exception {
                     .communicationStyle(current.communicationStyle())
                     .model(current.model())
                     .tools(current.tools())
+                    .expertiseEmbedding(current.expertiseEmbedding())
+                    .purposeEmbedding(current.purposeEmbedding())
+                    .soulVersion(current.soulVersion())
                     .createdAt(current.createdAt())
                     .updatedAt(Instant.now());
 

synapse/spector-synapse/src/main/java/com/spectrayan/spector/synapse/memory/UserMemoryRegistry.java

@@ -322,6 +322,11 @@ private SpectorMemory buildInstance(String userId) {
                         built.setSalienceProfile(model.salience());
                         log.info("[UserMemoryRegistry] Restored salience profile from INSULA for user/agent {}", userId);
                     }
+                    if (model != null && model.soul() != null) {
+                        built.setSoulVersion(model.soul().soulVersion());
+                        log.info("[UserMemoryRegistry] Restored soul version {} from INSULA for user/agent {}",
+                                model.soul().soulVersion(), userId);
+                    }
                 }
             }
         } catch (Exception e) {