@levalicious/server-memory 0.0.11 → 0.0.12

package/dist/src/pagerank.js

@@ -0,0 +1,78 @@
+/**
+ * PageRank sampling — structural rank via random walks on graph topology.
+ *
+ * Implements MC complete-path stopping at dangling nodes (Algorithm 4 from
+ * Avrachenkov et al. "Monte Carlo methods in PageRank computation").
+ *
+ * One "iteration" = one random walk starting from each node in the graph.
+ * Each walk follows forward edges with probability c (damping factor),
+ * terminates with probability (1-c) at each step, and stops immediately
+ * at dangling nodes (nodes with no forward edges).
+ *
+ * Every node visited along the walk gets its structuralVisits incremented.
+ * The global structuralTotal tracks the sum across all visits.
+ * PageRank(j) = structuralVisits(j) / structuralTotal.
+ *
+ * For 14K nodes with c=0.85, one iteration produces ~93K visits total
+ * (14K starts × ~6.67 avg walk length) and gives <7% error for top pages.
+ */
+import { DIR_FORWARD } from './graphfile.js';
+const DEFAULT_DAMPING = 0.85;
+/**
+ * Run one full iteration of structural PageRank sampling.
+ * Starts one random walk from every node in the graph.
+ *
+ * @param gf      GraphFile to sample on
+ * @param damping Probability of following a link (vs terminating). Default 0.85.
+ * @returns       Total number of visits recorded in this iteration.
+ */
+export function structuralIteration(gf, damping = DEFAULT_DAMPING) {
+    const offsets = gf.getAllEntityOffsets();
+    let totalVisits = 0;
+    for (const startOffset of offsets) {
+        totalVisits += structuralWalk(gf, startOffset, damping);
+    }
+    return totalVisits;
+}
+/**
+ * Run a single structural random walk starting from `startOffset`.
+ * Follows forward edges, counting every visited node (complete path).
+ * Stops at dangling nodes or with probability (1-damping) at each step.
+ *
+ * @returns Number of visits recorded in this walk.
+ */
+export function structuralWalk(gf, startOffset, damping = DEFAULT_DAMPING) {
+    let current = startOffset;
+    let visits = 0;
+    while (true) {
+        // Visit current node
+        gf.incrementStructuralVisit(current);
+        visits++;
+        // Get forward edges only
+        const edges = gf.getEdges(current);
+        const forward = edges.filter(e => e.direction === DIR_FORWARD);
+        // Dangling node — stop (Algorithm 4)
+        if (forward.length === 0)
+            break;
+        // Terminate with probability (1 - damping)
+        if (Math.random() >= damping)
+            break;
+        // Follow a random forward edge
+        const idx = Math.floor(Math.random() * forward.length);
+        current = forward[idx].targetOffset;
+    }
+    return visits;
+}
+/**
+ * Run N iterations of structural sampling.
+ * Each iteration = one walk from every node.
+ *
+ * @returns Total visits across all iterations.
+ */
+export function structuralSample(gf, iterations = 1, damping = DEFAULT_DAMPING) {
+    let total = 0;
+    for (let i = 0; i < iterations; i++) {
+        total += structuralIteration(gf, damping);
+    }
+    return total;
+}

package/dist/src/stringtable.js

@@ -0,0 +1,373 @@
+/**
+ * StringTable - Interned, refcounted string storage backed by a MemoryFile.
+ *
+ * Layout of each string entry (allocated via memfile_alloc):
+ *   [u32 refcount] [u32 hash] [u16 len] [u8 data[len]]
+ *
+ * String ID = the memfile offset to the entry (the offset returned by alloc,
+ * pointing past the memfile_alloc_t header, directly at refcount).
+ *
+ * The hash index is a separate allocated block:
+ *   [u32 bucket_count] [u32 _pad] [u64 offsets[bucket_count]]
+ *   Each bucket is the offset of the first entry in that bucket (0 = empty).
+ *   Collisions are resolved by linear probing.
+ *
+ * File header (after memfile header):
+ *   offset 32: [u64 hash_index_offset]
+ *   offset 40: [u32 entry_count]     total live strings
+ *   offset 44: [u32 _pad]
+ */
+import { MemoryFile } from './memoryfile.js';
+// We store our own header in an allocated block so it doesn't collide with
+// the memfile header region. The offset of this header block is stored at
+// a fixed position right after the memfile header.
+//
+// Our header block layout:
+//   [u64 hash_index_offset] [u32 entry_count] [u32 _pad]
+//
+// The pointer TO our header block is at memfile offset 32 (right after the
+// 32-byte memfile header). We write it there during init.
+//
+// BUT: offsets 32+ belong to the allocator. So we allocate a 16-byte block
+// for our header, and store its offset as the very first allocation.
+// Position in file where we store the offset to our header block.
+// This is a "well-known" location. We use the first allocation's offset.
+const OUR_HEADER_SIZE = 16; // u64 hash_index_offset + u32 entry_count + u32 pad
+// Offsets within our header block
+const HDR_HASH_INDEX_OFFSET = 0; // u64
+const HDR_ENTRY_COUNT = 8; // u32
+// String entry field offsets (relative to entry start)
+const ENT_REFCOUNT = 0; // u32
+const ENT_HASH = 4; // u32
+const ENT_LEN = 8; // u16
+const ENT_DATA = 10; // u8[len]
+const ENT_HEADER_SIZE = 10;
+// Hash index field offsets (relative to index block start)
+const IDX_BUCKET_COUNT = 0; // u32
+const IDX_BUCKETS = 8; // u64[bucket_count]
+const INITIAL_BUCKETS = 4096;
+const LOAD_FACTOR_THRESHOLD = 0.7;
+// FNV-1a 32-bit hash
+function fnv1a(data) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < data.length; i++) {
+        hash ^= data[i];
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0; // unsigned
+}
+export class StringTable {
+    mf;
+    headerOffset; // offset to our header block
+    constructor(path, initialSize = 65536) {
+        this.mf = new MemoryFile(path, initialSize);
+        const stats = this.mf.stats();
+        // A fresh memfile has allocated = 32 (just the memfile header).
+        // If anything has been allocated, the file was previously initialized.
+        if (stats.allocated <= 32n) {
+            this.headerOffset = this.initHeader();
+        }
+        else {
+            // The first allocation in the file is always our header block.
+            // It's at the first allocatable position after the memfile header.
+            // memfile_alloc returns the offset past the alloc_t header (8 bytes),
+            // so the first allocation is at offset 32 (memfile header) + 8 (alloc_t) = 40.
+            this.headerOffset = 40n;
+        }
+    }
+    initHeader() {
+        // Allocate our header block (first alloc in the file)
+        const hdrOffset = this.mf.alloc(BigInt(OUR_HEADER_SIZE));
+        if (hdrOffset === 0n)
+            throw new Error('StringTable: failed to allocate header');
+        // Allocate hash index block
+        const bucketBytes = INITIAL_BUCKETS * 8;
+        const indexSize = 4 + 4 + bucketBytes; // bucket_count + pad + buckets
+        const indexOffset = this.mf.alloc(BigInt(indexSize));
+        if (indexOffset === 0n)
+            throw new Error('StringTable: failed to allocate hash index');
+        // Write bucket_count to index block
+        const idxHeader = Buffer.alloc(8);
+        idxHeader.writeUInt32LE(INITIAL_BUCKETS, 0);
+        idxHeader.writeUInt32LE(0, 4); // pad
+        this.mf.write(indexOffset, idxHeader);
+        // Zero all buckets
+        const zeroBuckets = Buffer.alloc(bucketBytes);
+        this.mf.write(indexOffset + 8n, zeroBuckets);
+        // Write our header: hash_index_offset and entry_count
+        const hdr = Buffer.alloc(OUR_HEADER_SIZE);
+        hdr.writeBigUInt64LE(indexOffset, HDR_HASH_INDEX_OFFSET);
+        hdr.writeUInt32LE(0, HDR_ENTRY_COUNT); // entry_count = 0
+        hdr.writeUInt32LE(0, 12); // pad
+        this.mf.write(hdrOffset, hdr);
+        return hdrOffset;
+    }
+    // --- Header access ---
+    getHashIndexOffset() {
+        const buf = this.mf.read(this.headerOffset + BigInt(HDR_HASH_INDEX_OFFSET), 8n);
+        return buf.readBigUInt64LE(0);
+    }
+    getEntryCount() {
+        const buf = this.mf.read(this.headerOffset + BigInt(HDR_ENTRY_COUNT), 4n);
+        return buf.readUInt32LE(0);
+    }
+    setEntryCount(count) {
+        const buf = Buffer.alloc(4);
+        buf.writeUInt32LE(count, 0);
+        this.mf.write(this.headerOffset + BigInt(HDR_ENTRY_COUNT), buf);
+    }
+    // --- Hash index access ---
+    getBucketCount() {
+        const indexOffset = this.getHashIndexOffset();
+        const buf = this.mf.read(indexOffset, 4n);
+        return buf.readUInt32LE(0);
+    }
+    getBucket(index) {
+        const indexOffset = this.getHashIndexOffset();
+        const pos = indexOffset + BigInt(IDX_BUCKETS + index * 8);
+        const buf = this.mf.read(pos, 8n);
+        return buf.readBigUInt64LE(0);
+    }
+    setBucket(index, offset) {
+        const indexOffset = this.getHashIndexOffset();
+        const pos = indexOffset + BigInt(IDX_BUCKETS + index * 8);
+        const buf = Buffer.alloc(8);
+        buf.writeBigUInt64LE(offset, 0);
+        this.mf.write(pos, buf);
+    }
+    // --- String entry access ---
+    readEntry(offset) {
+        const header = this.mf.read(offset, BigInt(ENT_HEADER_SIZE));
+        const refcount = header.readUInt32LE(ENT_REFCOUNT);
+        const hash = header.readUInt32LE(ENT_HASH);
+        const len = header.readUInt16LE(ENT_LEN);
+        const data = len > 0 ? this.mf.read(offset + BigInt(ENT_DATA), BigInt(len)) : Buffer.alloc(0);
+        return { refcount, hash, len, data };
+    }
+    writeRefcount(offset, refcount) {
+        const buf = Buffer.alloc(4);
+        buf.writeUInt32LE(refcount, 0);
+        this.mf.write(offset, buf);
+    }
+    // --- Public API ---
+    /**
+     * Intern a string. Returns its ID (offset).
+     * If the string already exists, bumps refcount and returns existing ID.
+     * If new, allocates an entry and inserts into the hash index.
+     */
+    intern(str) {
+        const data = Buffer.from(str, 'utf-8');
+        const hash = fnv1a(data);
+        const bucketCount = this.getBucketCount();
+        let bucket = hash % bucketCount;
+        // Linear probe to find existing or empty slot
+        for (let i = 0; i < bucketCount; i++) {
+            const slotIdx = (bucket + i) % bucketCount;
+            const entryOffset = this.getBucket(slotIdx);
+            if (entryOffset === 0n) {
+                // Empty slot — string not found, allocate new entry
+                const entrySize = ENT_HEADER_SIZE + data.length;
+                const newOffset = this.mf.alloc(BigInt(entrySize));
+                if (newOffset === 0n)
+                    throw new Error('StringTable: alloc failed');
+                // Write entry: refcount=1, hash, len, data
+                const entryBuf = Buffer.alloc(ENT_HEADER_SIZE);
+                entryBuf.writeUInt32LE(1, ENT_REFCOUNT);
+                entryBuf.writeUInt32LE(hash, ENT_HASH);
+                entryBuf.writeUInt16LE(data.length, ENT_LEN);
+                this.mf.write(newOffset, entryBuf);
+                if (data.length > 0) {
+                    this.mf.write(newOffset + BigInt(ENT_DATA), data);
+                }
+                // Insert into hash index
+                this.setBucket(slotIdx, newOffset);
+                const count = this.getEntryCount() + 1;
+                this.setEntryCount(count);
+                // Check load factor and rehash if needed
+                if (count > bucketCount * LOAD_FACTOR_THRESHOLD) {
+                    this.rehash(bucketCount * 2);
+                }
+                return newOffset;
+            }
+            // Slot occupied — check if it matches
+            const entry = this.readEntry(entryOffset);
+            if (entry.hash === hash && entry.len === data.length && entry.data.equals(data)) {
+                // Found — bump refcount
+                this.writeRefcount(entryOffset, entry.refcount + 1);
+                return entryOffset;
+            }
+            // Collision — continue probing
+        }
+        throw new Error('StringTable: hash index full (should not happen with rehashing)');
+    }
+    /**
+     * Get the string for an ID. Returns the UTF-8 string.
+     */
+    get(id) {
+        const entry = this.readEntry(id);
+        return entry.data.toString('utf-8');
+    }
+    /**
+     * Look up a string without interning or bumping refcount.
+     * Returns the ID (offset) if found, or null if not present.
+     */
+    find(str) {
+        const data = Buffer.from(str, 'utf-8');
+        const hash = fnv1a(data);
+        const bucketCount = this.getBucketCount();
+        let bucket = hash % bucketCount;
+        for (let i = 0; i < bucketCount; i++) {
+            const slotIdx = (bucket + i) % bucketCount;
+            const entryOffset = this.getBucket(slotIdx);
+            if (entryOffset === 0n)
+                return null; // Empty slot — not found
+            const entry = this.readEntry(entryOffset);
+            if (entry.hash === hash && entry.len === data.length && entry.data.equals(data)) {
+                return entryOffset;
+            }
+        }
+        return null;
+    }
+    /**
+     * Decrement refcount. If it reaches 0, free the entry and remove from hash index.
+     */
+    release(id) {
+        const entry = this.readEntry(id);
+        if (entry.refcount <= 1) {
+            // Remove from hash index
+            this.removeFromIndex(id, entry.hash);
+            // Free the allocation
+            this.mf.free(id);
+            this.setEntryCount(this.getEntryCount() - 1);
+        }
+        else {
+            this.writeRefcount(id, entry.refcount - 1);
+        }
+    }
+    /**
+     * Bump refcount without interning (for when you already have the ID).
+     */
+    addRef(id) {
+        const entry = this.readEntry(id);
+        this.writeRefcount(id, entry.refcount + 1);
+    }
+    /**
+     * Get current refcount for an entry.
+     */
+    refcount(id) {
+        const buf = this.mf.read(id, 4n);
+        return buf.readUInt32LE(0);
+    }
+    /**
+     * Number of live strings in the table.
+     */
+    get count() {
+        return this.getEntryCount();
+    }
+    // --- Hash index management ---
+    removeFromIndex(offset, hash) {
+        const bucketCount = this.getBucketCount();
+        let bucket = hash % bucketCount;
+        // Find the entry in the index
+        for (let i = 0; i < bucketCount; i++) {
+            const slotIdx = (bucket + i) % bucketCount;
+            const entryOffset = this.getBucket(slotIdx);
+            if (entryOffset === 0n)
+                return; // Not found (shouldn't happen)
+            if (entryOffset === offset) {
+                // Found — remove and fix up the linear probe chain
+                this.setBucket(slotIdx, 0n);
+                this.fixupAfterRemoval(slotIdx, bucketCount);
+                return;
+            }
+        }
+    }
+    /**
+     * After removing an entry at slotIdx, re-insert any entries that were
+     * displaced past the removed slot by linear probing.
+     */
+    fixupAfterRemoval(removedSlot, bucketCount) {
+        let slot = (removedSlot + 1) % bucketCount;
+        while (true) {
+            const entryOffset = this.getBucket(slot);
+            if (entryOffset === 0n)
+                break; // End of cluster
+            // Read this entry's natural bucket
+            const entry = this.readEntry(entryOffset);
+            const naturalBucket = entry.hash % bucketCount;
+            // Check if this entry needs to move (it was displaced past removedSlot)
+            if (this.needsRelocation(naturalBucket, removedSlot, slot, bucketCount)) {
+                this.setBucket(removedSlot, entryOffset);
+                this.setBucket(slot, 0n);
+                // Continue fixup from the newly emptied slot
+                removedSlot = slot;
+            }
+            slot = (slot + 1) % bucketCount;
+        }
+    }
+    needsRelocation(natural, empty, current, size) {
+        // Is 'empty' between 'natural' and 'current' in the circular probe sequence?
+        if (natural <= current) {
+            return natural <= empty && empty < current;
+        }
+        else {
+            // Wraps around
+            return natural <= empty || empty < current;
+        }
+    }
+    rehash(newBucketCount) {
+        const oldIndexOffset = this.getHashIndexOffset();
+        const oldBucketCount = this.getBucketCount();
+        // Allocate new index
+        const newIndexSize = 4 + 4 + newBucketCount * 8;
+        const newIndexOffset = this.mf.alloc(BigInt(newIndexSize));
+        if (newIndexOffset === 0n)
+            throw new Error('StringTable: rehash alloc failed');
+        // Write new bucket count
+        const header = Buffer.alloc(8);
+        header.writeUInt32LE(newBucketCount, 0);
+        this.mf.write(newIndexOffset, header);
+        // Zero new buckets
+        const zeroBuckets = Buffer.alloc(newBucketCount * 8);
+        this.mf.write(newIndexOffset + 8n, zeroBuckets);
+        // Update header to point to new index
+        const hdr = Buffer.alloc(8);
+        hdr.writeBigUInt64LE(newIndexOffset, 0);
+        this.mf.write(this.headerOffset + BigInt(HDR_HASH_INDEX_OFFSET), hdr);
+        // Re-insert all entries from old index
+        for (let i = 0; i < oldBucketCount; i++) {
+            const pos = oldIndexOffset + BigInt(IDX_BUCKETS + i * 8);
+            const buf = this.mf.read(pos, 8n);
+            const entryOffset = buf.readBigUInt64LE(0);
+            if (entryOffset === 0n)
+                continue;
+            // Read hash and insert into new index
+            const entry = this.readEntry(entryOffset);
+            let bucket = entry.hash % newBucketCount;
+            for (let j = 0; j < newBucketCount; j++) {
+                const slotIdx = (bucket + j) % newBucketCount;
+                const slotPos = newIndexOffset + BigInt(IDX_BUCKETS + slotIdx * 8);
+                const slotBuf = this.mf.read(slotPos, 8n);
+                if (slotBuf.readBigUInt64LE(0) === 0n) {
+                    const writeBuf = Buffer.alloc(8);
+                    writeBuf.writeBigUInt64LE(entryOffset, 0);
+                    this.mf.write(slotPos, writeBuf);
+                    break;
+                }
+            }
+        }
+        // Free old index block
+        this.mf.free(oldIndexOffset);
+    }
+    // --- Lifecycle ---
+    sync() {
+        this.mf.sync();
+    }
+    /** Refresh the mmap if the file was grown by another process. */
+    refresh() {
+        this.mf.refresh();
+    }
+    close() {
+        this.mf.close();
+    }
+}

package/dist/tests/concurrency.test.js

@@ -0,0 +1,189 @@
+/**
+ * Concurrency tests: two MCP server instances sharing the same binary files.
+ *
+ * Verifies that flock-based locking + mmap refresh works correctly when
+ * one instance writes and the other reads.
+ */
+import { createServer } from "../server.js";
+import { createTestClient, callTool } from "./test-utils.js";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+describe("Concurrency - dual server instances", () => {
+    let tmpDir;
+    let memoryFilePath;
+    let clientA;
+    let clientB;
+    let cleanupA;
+    let cleanupB;
+    beforeEach(async () => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "memory-concurrency-"));
+        memoryFilePath = path.join(tmpDir, "memory.json");
+        // Create two MCP server instances sharing the same files
+        const serverA = createServer(memoryFilePath);
+        const serverB = createServer(memoryFilePath);
+        const setupA = await createTestClient(serverA);
+        const setupB = await createTestClient(serverB);
+        clientA = setupA.client;
+        clientB = setupB.client;
+        cleanupA = setupA.cleanup;
+        cleanupB = setupB.cleanup;
+    });
+    afterEach(async () => {
+        await cleanupA();
+        await cleanupB();
+        // Clean up temp files
+        const files = fs.readdirSync(tmpDir);
+        for (const f of files) {
+            fs.unlinkSync(path.join(tmpDir, f));
+        }
+        fs.rmdirSync(tmpDir);
+    });
+    it("instance B sees entities created by instance A", async () => {
+        // A creates entities
+        await callTool(clientA, "create_entities", {
+            entities: [
+                { name: "Alpha", entityType: "Letter", observations: ["First letter"] },
+                { name: "Beta", entityType: "Letter", observations: ["Second letter"] },
+            ],
+        });
+        // B should see them
+        const result = (await callTool(clientB, "search_nodes", {
+            query: "Letter",
+            sortBy: "name",
+        }));
+        const names = result.entities.items.map((e) => e.name);
+        expect(names).toEqual(["Alpha", "Beta"]);
+    });
+    it("instance B sees relations created by instance A", async () => {
+        // A creates entities
+        await callTool(clientA, "create_entities", {
+            entities: [
+                { name: "Node1", entityType: "Test", observations: [] },
+                { name: "Node2", entityType: "Test", observations: [] },
+            ],
+        });
+        // A creates relation
+        await callTool(clientA, "create_relations", {
+            relations: [{ from: "Node1", to: "Node2", relationType: "links_to" }],
+        });
+        // B reads neighbors
+        const result = (await callTool(clientB, "get_neighbors", {
+            entityName: "Node1",
+            sortBy: "name",
+        }));
+        expect(result.items).toHaveLength(1);
+        expect(result.items[0].name).toBe("Node2");
+    });
+    it("instance A sees entities created by instance B", async () => {
+        // B creates entities
+        await callTool(clientB, "create_entities", {
+            entities: [
+                { name: "Gamma", entityType: "Letter", observations: ["Third letter"] },
+            ],
+        });
+        // A should see them
+        const result = (await callTool(clientA, "open_nodes", {
+            names: ["Gamma"],
+        }));
+        expect(result.entities.items).toHaveLength(1);
+        expect(result.entities.items[0].name).toBe("Gamma");
+        expect(result.entities.items[0].observations).toEqual(["Third letter"]);
+    });
+    it("interleaved writes are visible to both instances", async () => {
+        // A creates first entity
+        await callTool(clientA, "create_entities", {
+            entities: [{ name: "E1", entityType: "Interleaved", observations: [] }],
+        });
+        // B creates second entity
+        await callTool(clientB, "create_entities", {
+            entities: [{ name: "E2", entityType: "Interleaved", observations: [] }],
+        });
+        // A creates third entity
+        await callTool(clientA, "create_entities", {
+            entities: [{ name: "E3", entityType: "Interleaved", observations: [] }],
+        });
+        // Both should see all 3
+        const resultA = (await callTool(clientA, "search_nodes", {
+            query: "Interleaved",
+            sortBy: "name",
+        }));
+        const resultB = (await callTool(clientB, "search_nodes", {
+            query: "Interleaved",
+            sortBy: "name",
+        }));
+        const namesA = resultA.entities.items.map((e) => e.name);
+        const namesB = resultB.entities.items.map((e) => e.name);
+        expect(namesA).toEqual(["E1", "E2", "E3"]);
+        expect(namesB).toEqual(["E1", "E2", "E3"]);
+    });
+    it("deletions by A are visible to B", async () => {
+        // A creates entities
+        await callTool(clientA, "create_entities", {
+            entities: [
+                { name: "Keep", entityType: "Test", observations: [] },
+                { name: "Remove", entityType: "Test", observations: [] },
+            ],
+        });
+        // A deletes one
+        await callTool(clientA, "delete_entities", {
+            entityNames: ["Remove"],
+        });
+        // B should only see the remaining one
+        const result = (await callTool(clientB, "search_nodes", {
+            query: "Test",
+            sortBy: "name",
+        }));
+        const names = result.entities.items.map((e) => e.name);
+        expect(names).toEqual(["Keep"]);
+    });
+    it("observation changes by A are visible to B", async () => {
+        // A creates entity
+        await callTool(clientA, "create_entities", {
+            entities: [{ name: "Observable", entityType: "Test", observations: ["Initial"] }],
+        });
+        // A adds observation
+        await callTool(clientA, "add_observations", {
+            observations: [{ entityName: "Observable", contents: ["Added by A"] }],
+        });
+        // B reads it
+        const result = (await callTool(clientB, "open_nodes", {
+            names: ["Observable"],
+        }));
+        expect(result.entities.items[0].observations).toContain("Initial");
+        expect(result.entities.items[0].observations).toContain("Added by A");
+    });
+    it("stats are consistent across instances", async () => {
+        // A creates entities and relations
+        await callTool(clientA, "create_entities", {
+            entities: [
+                { name: "S1", entityType: "Stats", observations: [] },
+                { name: "S2", entityType: "Stats", observations: [] },
+            ],
+        });
+        await callTool(clientA, "create_relations", {
+            relations: [{ from: "S1", to: "S2", relationType: "related" }],
+        });
+        // B checks stats
+        const stats = (await callTool(clientB, "get_stats", {}));
+        expect(stats.entityCount).toBe(2);
+        expect(stats.relationCount).toBe(1);
+    });
+    it("handles many entities created across instances (growth/remap)", async () => {
+        // Create enough entities to trigger file growth
+        const batchA = [];
+        const batchB = [];
+        for (let i = 0; i < 50; i++) {
+            batchA.push({ name: `A_${i}`, entityType: "Bulk", observations: [`Obs ${i}`] });
+            batchB.push({ name: `B_${i}`, entityType: "Bulk", observations: [`Obs ${i}`] });
+        }
+        // Create in parallel-ish: A first, then B
+        await callTool(clientA, "create_entities", { entities: batchA });
+        await callTool(clientB, "create_entities", { entities: batchB });
+        // Both see all 100
+        const statsA = (await callTool(clientA, "get_stats", {}));
+        const statsB = (await callTool(clientB, "get_stats", {}));
+        expect(statsA.entityCount).toBe(100);
+        expect(statsB.entityCount).toBe(100);
+    });
+});