feat: Implement Native Edge SQLite Graph Persistence (#9678)

Author: tobiu

ai/graph/Database.mjs

@@ -3,6 +3,7 @@ import ClassSystemUtil from '../../src/util/ClassSystem.mjs';
 import Store           from './Store.mjs';
 import EdgeModel       from './EdgeModel.mjs';
 import NodeModel       from './NodeModel.mjs';
+import StorageBase     from './storage/Base.mjs';
 
 /**
  * The Database class serves as the core coordinator for the Native Edge Graph Database engine. 
@@ -20,6 +21,10 @@ class Database extends Base {
          * @protected
          */
         className: 'Neo.ai.graph.Database',
+        /**
+         * @member {Boolean} autoSave=true
+         */
+        autoSave: true,
         /**
          * @member {Object|Neo.data.Store|null} edges_=null
          * @reactive
@@ -29,7 +34,13 @@ class Database extends Base {
          * @member {Object|Neo.data.Store|null} nodes_=null
          * @reactive
          */
-        nodes_: null
+        nodes_: null,
+        /**
+         * Database persistence wrapper.
+         * @member {Object|Neo.ai.graph.storage.Base|null} storage_=null
+         * @reactive
+         */
+        storage_: null
     }
 
     /**
@@ -50,6 +61,18 @@ class Database extends Base {
         this.nodes.add(node);
     }
 
+    /**
+     * Triggered after the storage config gets changed.
+     * @param {Neo.ai.graph.storage.Base} value
+     * @param {Neo.ai.graph.storage.Base} oldValue
+     * @protected
+     */
+    afterSetStorage(value, oldValue) {
+        if (value) {
+            value.load();
+        }
+    }
+
     /**
      * Triggered before the edges config gets changed.
      * @param {Object|Neo.data.Store} value
@@ -59,11 +82,15 @@ class Database extends Base {
      */
     beforeSetEdges(value, oldValue) {
         oldValue?.destroy();
-        return ClassSystemUtil.beforeSetInstance(value, Store, {
+        let store = ClassSystemUtil.beforeSetInstance(value, Store, {
             autoInitRecords: false,
             indices        : [{ property: 'source' }, { property: 'target' }],
             model          : EdgeModel
         });
+
+        store?.on('mutate', this.onEdgesMutate, this);
+
+        return store;
     }
 
     /**
@@ -75,10 +102,32 @@ class Database extends Base {
      */
     beforeSetNodes(value, oldValue) {
         oldValue?.destroy();
-        return ClassSystemUtil.beforeSetInstance(value, Store, {
+        let store = ClassSystemUtil.beforeSetInstance(value, Store, {
             autoInitRecords: false,
             model          : NodeModel
         });
+
+        store?.on('mutate', this.onNodesMutate, this);
+
+        return store;
+    }
+
+    /**
+     * Triggered before the storage config gets changed.
+     * @param {Object|Neo.ai.graph.storage.Base} value
+     * @param {Object|Neo.ai.graph.storage.Base} oldValue
+     * @returns {Neo.ai.graph.storage.Base}
+     * @protected
+     */
+    beforeSetStorage(value, oldValue) {
+        if (value) {
+            value = ClassSystemUtil.beforeSetInstance(value, StorageBase, {
+                database: this
+            });
+            
+            value.database = this;
+        }
+        return value;
     }
 
     /**
@@ -130,6 +179,36 @@ class Database extends Base {
         return nodes;
     }
 
+    /**
+     * Triggered on edges Store mutations to sync storage
+     * @param {Object} mutation
+     */
+    onEdgesMutate(mutation) {
+        if (this.autoSave && this.storage) {
+            if (mutation.addedItems?.length > 0) {
+                this.storage.addEdges(mutation.addedItems);
+            }
+            if (mutation.removedItems?.length > 0) {
+                this.storage.removeEdges(mutation.removedItems);
+            }
+        }
+    }
+
+    /**
+     * Triggered on nodes Store mutations to sync storage
+     * @param {Object} mutation
+     */
+    onNodesMutate(mutation) {
+        if (this.autoSave && this.storage) {
+            if (mutation.addedItems?.length > 0) {
+                this.storage.addNodes(mutation.addedItems);
+            }
+            if (mutation.removedItems?.length > 0) {
+                this.storage.removeNodes(mutation.removedItems);
+            }
+        }
+    }
+
     /**
      * Removes an edge from the Native Edge Graph Database topology.
      * @param {String} edgeId

ai/graph/storage/Base.mjs

@@ -0,0 +1,60 @@
+import NeoBase from '../../../src/core/Base.mjs';
+
+/**
+ * The abstract blueprint defining the core interaction envelope for Native Edge Persistor paradigms.
+ * Storage engines extending this Base dynamically coordinate structural object ingestion, schema mapping,
+ * and GraphRAG disk mutations synchronized instantly against memory traversals bounding the Neo MCP ecosystem.
+ * 
+ * @class Neo.ai.graph.storage.Base
+ * @extends Neo.core.Base
+ */
+class Base extends NeoBase {
+    static config = {
+        /**
+         * @member {String} className='Neo.ai.graph.storage.Base'
+         * @protected
+         */
+        className: 'Neo.ai.graph.storage.Base',
+        /**
+         * Database instance reference
+         * @member {Neo.ai.graph.Database|null} database=null
+         */
+        database: null
+    }
+
+    /**
+     * Executes bulk topology injections mapping dynamic array structures into rigid Node.js endpoints.
+     * @param {Object[]} nodes
+     */
+    addNodes(nodes) {}
+
+    /**
+     * Projects bidirectional edge matrices into structural persistence mechanisms preventing topological drift.
+     * @param {Object[]} edges
+     */
+    addEdges(edges) {}
+
+    /**
+     * Purges specific Nodes array data natively resolving cascade anomalies internally at the driver stratum.
+     * @param {Object[]} nodes
+     */
+    removeNodes(nodes) {}
+
+    /**
+     * Exterminates specified Edge links synchronously tracking physical memory un-mappings.
+     * @param {Object[]} edges
+     */
+    removeEdges(edges) {}
+
+    /**
+     * Annihilates the local physical footprint entirely. Used exclusively to reset Graph matrices to zero state natively.
+     */
+    clear() {}
+
+    /**
+     * Orchestrates the restoration loop, ripping physical rows back out into standard `Neo.data.Record` collections internally.
+     */
+    async load() {}
+}
+
+export default Neo.setupClass(Base);