fix(memory): V4 bundle wiring, region slice reservation, and BM25 sizing (#508)

Fixes V4 bundle ingestion & sidecar elimination:
- Default useBundleMode to true in SpectorMemoryBuilder per ADR-0004
- Reserve 32B/entity for name index in ENTITY_NAMES region so adjCap calculation doesn't overflow slice
- Store checkpointRegion in CoActivationRecordMemory constructor so save() writes to CHECKPOINT region
- Pass checkpointRegion slice to CheckpointDaemon and CoActivationRecordMemory
- Increase BM25 initial region size formula to scale from episodicPartitionCapacity (4MB min)
- Check for CHECKPOINT and BM25 regions when validating open runtime bundles
- Prefer BM25 region save on close/rebuild, avoiding unneeded standalone bm25.bidx creation

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

Author: forgespectrayan

memory/spector-memory/src/main/java/com/spectrayan/spector/memory/BiologicalSubsystemsBuilder.java

@@ -76,9 +76,10 @@ static BiologicalSubsystems build(SpectorMemoryBuilder builder,
         if (cortex.useBundleMode() && cortex.runtimeBundle() != null) {
             java.lang.foreign.MemorySegment regionSlice = cortex.runtimeBundle().regionSegment(com.spectrayan.spector.memory.kernel.bundle.RegionId.COACTIVATION);
             boolean isNew = !com.spectrayan.spector.memory.kernel.MemoryHeader.isValid(regionSlice, 0L);
+            java.lang.foreign.MemorySegment ckptSlice = cortex.runtimeBundle().regionSegment(com.spectrayan.spector.memory.kernel.bundle.RegionId.CHECKPOINT);
             coActivationTracker = CoActivationRecordMemory.fromBundle(
                     cortex.runtimeBundle().arena(), regionSlice, 10_000, 20_000,
-                    StorageLayout.coactivationTracker(basePath), isNew);
+                    StorageLayout.coactivationTracker(basePath), isNew, ckptSlice);
         } else if (isDisk && basePath != null) {
             coActivationTracker = CoActivationRecordMemory.load(
                     StorageLayout.coactivationTracker(basePath), 10_000, 20_000);

memory/spector-memory/src/main/java/com/spectrayan/spector/memory/CognitiveCortexBuilder.java

@@ -309,8 +309,8 @@ private static List<RegionSizeSpec> getRuntimeBundleSpecs(SpectorMemoryBuilder b
         long typeRegistrySize = builder.typeRegistrySize;
         long insulaSize = builder.insulaSize;
 
-        // BM25 region sizing: header(24) + docIds(~48B/doc) + docLengths(4B/doc) + terms+postings(~80B/doc)
-        long bm25InitialSize = Math.max(64 * 1024, 24 + 132L * workingCap);
+        // BM25 region sizing: header(24) + docIds(~48B/doc) + docLengths(4B/doc) + terms+postings(~1400B/doc)
+        long bm25InitialSize = Math.max(4L * 1024 * 1024, 24 + 1500L * builder.episodicPartitionCapacity);
 
         return List.of(
                 new RegionSizeSpec(

memory/spector-memory/src/main/java/com/spectrayan/spector/memory/DaemonSupervisorBuilder.java

@@ -61,14 +61,17 @@ static DaemonBundle build(
             Path indexSavePath = resolvedPartitionDir != null
                     ? resolvedPartitionDir.resolve(StorageLayout.FILE_INDEX)
                     : StorageLayout.indexMidxRuntime(basePath);
+            java.lang.foreign.MemorySegment ckptSlice = cortex.useBundleMode() && cortex.runtimeBundle() != null
+                    ? cortex.runtimeBundle().regionSegment(com.spectrayan.spector.memory.kernel.bundle.RegionId.CHECKPOINT)
+                    : null;
             checkpointDaemon = new CheckpointDaemon(
                     cortex.cognitiveRouter(), wal,
                     StorageLayout.checkpointMeta(basePath),
                     index, indexSavePath,
                     graphs.hebbianGraph(), graphs.temporalChain(),
                     graphs.entityDirectory(), graphs.hyperEntityGraph(), bio.coActivationTracker(),
                     graphs.temporalKnowledgeGraph(),
-                    resolvedPartitionDir, basePath);
+                    resolvedPartitionDir, basePath, ckptSlice);
             daemonSupervisor = new DaemonSupervisor("memory");
             daemonSupervisor.schedule(
                     "checkpoint",

memory/spector-memory/src/main/java/com/spectrayan/spector/memory/DefaultSpectorMemory.java

@@ -1423,11 +1423,26 @@ private void doClose() {
         if (persistenceMode == MemoryPersistenceMode.DISK
                 && partitionManager.activePartitionDir() != null
                 && bm25Index != null && bm25Index.totalDocuments() > 0) {
-            try {
-                bm25Index.partition(0).save(
-                        StorageLayout.bm25BidxRuntime(persistencePath));
-            } catch (Exception e) {
-                log.warn("Failed to save BM25 index on close: {}", e.getMessage());
+            boolean savedToBundle = false;
+            if (runtimeBundle != null) {
+                try {
+                    java.lang.foreign.MemorySegment bm25Region = runtimeBundle.regionSegment(
+                            com.spectrayan.spector.memory.kernel.bundle.RegionId.BM25);
+                    if (bm25Region != null) {
+                        int written = bm25Index.partition(0).saveToRegion(bm25Region);
+                        savedToBundle = written > 0;
+                    }
+                } catch (Exception e) {
+                    log.debug("BM25 bundle region save on close failed: {}", e.getMessage());
+                }
+            }
+            if (!savedToBundle) {
+                try {
+                    bm25Index.partition(0).save(
+                            StorageLayout.bm25BidxRuntime(persistencePath));
+                } catch (Exception e) {
+                    log.warn("Failed to save BM25 index on close: {}", e.getMessage());
+                }
             }
             // V4 bundle: save to BM25 region
             if (runtimeBundle != null) {

memory/spector-memory/src/main/java/com/spectrayan/spector/memory/RetrievalIndexBuilder.java

@@ -114,20 +114,24 @@ static RetrievalIndices build(SpectorMemoryBuilder builder,
                 if (!allTexts.isEmpty()) {
                     bm25Index.rebuildPartition(0, allTexts);
                     log.info("Rebuilt BM25 index with {} documents from memory index", allTexts.size());
-                    // Save to file (V3 compat) and bundle region (V4)
-                    java.nio.file.Path bm25Path = StorageLayout.bm25BidxRuntime(basePath);
-                    bm25Index.partition(0).save(bm25Path);
+                    // Save to bundle region (V4) or file (V3 fallback)
+                    boolean savedToBundle = false;
                     if (cortex.useBundleMode() && cortex.runtimeBundle() != null) {
                         try {
                             java.lang.foreign.MemorySegment bm25Region = cortex.runtimeBundle().regionSegment(
                                     com.spectrayan.spector.memory.kernel.bundle.RegionId.BM25);
                             if (bm25Region != null) {
-                                bm25Index.partition(0).saveToRegion(bm25Region);
+                                int written = bm25Index.partition(0).saveToRegion(bm25Region);
+                                savedToBundle = written > 0;
                             }
                         } catch (Exception e) {
                             log.debug("BM25 bundle region save failed: {}", e.getMessage());
                         }
                     }
+                    if (!savedToBundle) {
+                        java.nio.file.Path bm25Path = StorageLayout.bm25BidxRuntime(basePath);
+                        bm25Index.partition(0).save(bm25Path);
+                    }
                 }
             }
         } else {

memory/spector-memory/src/main/java/com/spectrayan/spector/memory/SpectorMemoryBuilder.java

@@ -64,7 +64,7 @@ public final class SpectorMemoryBuilder {
 
     //  Core configuration 
     boolean managedByRegistry = false;
-    boolean useBundleMode = false;  // V4 bundle architecture (ADR-0004)
+    boolean useBundleMode = true;   // V4 bundle architecture (ADR-0004)
     int dimensions;
     EmbeddingProvider embeddingProvider;
     Path persistencePath;

memory/spector-memory/src/main/java/com/spectrayan/spector/memory/graph/EntityDirectory.java

@@ -192,7 +192,9 @@ private EntityDirectory(Arena arena, MemorySegment entityRegionSlice, MemorySegm
             MemoryHeader.write(adjacencyRegionSlice, 0L, LAYOUT.schemaVersion(), MemoryShape.GRAPH, 0,
                     (int) adjacencyRegionSlice.byteSize(), 0, 0, LAYOUT.layoutId(), now, now);
 
-            int adjCap = (int) ((adjacencyRegionSlice.byteSize() - MemoryHeader.HEADER_BYTES - 16) / ADJ_ENTRY_BYTES);
+            long reservedForNames = 32L * entityCapacity;
+            long availableForAdj = Math.max(0, adjacencyRegionSlice.byteSize() - MemoryHeader.HEADER_BYTES - 16 - reservedForNames);
+            int adjCap = (int) (availableForAdj / ADJ_ENTRY_BYTES);
             adjacencyRegionSlice.set(ValueLayout.JAVA_INT, headerStart + SUB_OFF_ADJ_CAPACITY, adjCap);
             adjacencyRegionSlice.set(ValueLayout.JAVA_INT, headerStart + SUB_OFF_ADJ_HWM, 0);
             this.adjSegmentCapacity = adjCap;

memory/spector-memory/src/main/java/com/spectrayan/spector/memory/graph/TypeRegistryMemory.java

@@ -213,8 +213,8 @@ public static TypeRegistryMemory fromBundle(SystemMemoryId systemMemoryId, Arena
     public void save(Path filePath) throws IOException {
         if (bundleManaged) {
             long now = System.currentTimeMillis();
-            MemoryHeader.write(bundleSlice, 0L, backing.layout().schemaVersion(), MemoryShape.REGISTRY, backing.size(),
-                    (int) bundleSlice.byteSize(), 0, 0, backing.layout().layoutId(), now, now);
+            MemoryHeader.write(bundleSlice, 0L, backing.layout().schemaVersion(), MemoryShape.REGISTRY, 0,
+                    backing.capacity(), backing.size(), backing.layout().recordStride(), backing.layout().layoutId(), now, now);
             backing.flush();
             log.info("{} registry saved to bundle: {} types", label, backing.size());
             return;

memory/spector-memory/src/main/java/com/spectrayan/spector/memory/hebbian/CoActivationRecordMemory.java

@@ -187,6 +187,7 @@ private CoActivationRecordMemory(Arena arena, MemorySegment regionSlice,
               pairCap, arena, regionSlice,
               isNew ? 0 : (int) MemoryHeader.readCount(regionSlice, 0),
               true, bundlePath, null, true); // bundleManaged=true
+        this.checkpointRegion = checkpointRegion;
 
         long totalBytes = 8 + 32L * pairCap + 40L * edgeCap;
         MemorySegment segment = segment();

memory/spector-memory/src/main/java/com/spectrayan/spector/memory/index/IndexRecordMemory.java

@@ -704,14 +704,14 @@ public void save(Path filePath) {
                 long totalSlotBytes = (long) entryCount * stride;
 
                 long now = System.currentTimeMillis();
-                MemoryHeader.write(bundleMidxSlice, 0L, INDEX_VERSION_V7, MemoryShape.RECORD, entryCount,
-                        (int) (MemoryHeader.HEADER_BYTES + totalSlotBytes), 0, 0, new IndexEntryLayout().layoutId(), now, now);
+                MemoryHeader.write(bundleMidxSlice, 0L, INDEX_VERSION_V7, MemoryShape.RECORD, 0,
+                        100_000L, entryCount, stride, new IndexEntryLayout().layoutId(), now, now);
                 // Persist graphSlotHighWater in the reserved field (offset 60, outside CRC range)
                 long headerBaseOffset = 0L;
                 bundleMidxSlice.set(java.lang.foreign.ValueLayout.JAVA_INT_UNALIGNED, headerBaseOffset + 60, graphSlotHighWater.get());
 
-                MemoryHeader.write(bundleIdplSlice, 0L, 1, MemoryShape.APPEND, entryCount,
-                        (int) (MemoryHeader.HEADER_BYTES + totalPoolBytes), 0, 0, new IdBlobLayout().layoutId(), now, now);
+                MemoryHeader.write(bundleIdplSlice, 0L, 1, MemoryShape.APPEND, 0,
+                        totalPoolBytes, entryCount, 0, new IdBlobLayout().layoutId(), now, now);
 
                 long poolOffset = 0;
                 int index = 0;
@@ -729,7 +729,7 @@ public void save(Path filePath) {
                     ByteBuffer slotBuf = ByteBuffer.wrap(slotBytes);
                     slotBuf.order(java.nio.ByteOrder.nativeOrder());
 
-                    slotBuf.putLong(poolOffset);
+                    slotBuf.putLong(poolOffset + 4);
                     slotBuf.putInt(blobBytes.length);
                     slotBuf.putInt(loc.type().ordinal());
                     slotBuf.putLong(loc.offset());