aifastdb 2.8.0 → 2.8.2

package/dist/social-graph-v2.js

@@ -119,6 +119,15 @@ class SocialGraphV2 {
                 maxElements: config.vectorSearch.maxElements,
                 shardCount: config.vectorSearch.shardCount,
             } : undefined,
+            textSearch: config.textSearch ? {
+                enableChinese: config.textSearch.enableChinese,
+                userDictPath: config.textSearch.userDictPath,
+                synonymPath: config.textSearch.synonymPath,
+                customStopWordsPath: config.textSearch.customStopWordsPath,
+                enableStopWords: config.textSearch.enableStopWords,
+                enableStemmer: config.textSearch.enableStemmer,
+                autoCommit: config.textSearch.autoCommit,
+            } : undefined,
         });
     }
     /**
@@ -430,6 +439,538 @@ class SocialGraphV2 {
         return this.native.removeBirthday(personId);
     }
     // ========================================================================
+    // Birthday Advanced Queries (Phase-114)
+    // ========================================================================
+    /**
+     * Find people with exact same birthday (same year-month-day)
+     *
+     * @param birthday - Birthday in YYYY-MM-DD format
+     * @returns Array of person entities with matching birthday
+     *
+     * @example
+     * ```typescript
+     * const matches = social.findSameBirthdayExact('1990-03-15');
+     * console.log(`${matches.length} people born on 1990-03-15`);
+     * ```
+     */
+    findSameBirthdayExact(birthday) {
+        return this.native.findSameBirthdayExact(birthday);
+    }
+    /**
+     * Find people with same month-day birthday (different years allowed)
+     *
+     * @param birthday - Birthday in YYYY-MM-DD or MM-DD format
+     * @returns Array of person entities with matching month-day
+     *
+     * @example
+     * ```typescript
+     * const matches = social.findSameBirthdayDayMonth('03-15');
+     * console.log(`${matches.length} people born on March 15th`);
+     * ```
+     */
+    findSameBirthdayDayMonth(birthday) {
+        return this.native.findSameBirthdayDayMonth(birthday);
+    }
+    /**
+     * Find people with same exact birthday as a given person
+     *
+     * @param personId - The person ID to match against
+     * @returns Array of person entities (excludes the person themselves)
+     *
+     * @example
+     * ```typescript
+     * const twins = social.findSameBirthdayAsPersonExact(alice.id);
+     * console.log(`${twins.length} people share Alice's exact birthday`);
+     * ```
+     */
+    findSameBirthdayAsPersonExact(personId) {
+        return this.native.findSameBirthdayAsPersonExact(personId);
+    }
+    /**
+     * Find people with same month-day birthday as a given person (different years allowed)
+     *
+     * @param personId - The person ID to match against
+     * @returns Array of person entities (excludes the person themselves)
+     *
+     * @example
+     * ```typescript
+     * const matches = social.findSameBirthdayAsPerson(alice.id);
+     * console.log(`${matches.length} people share Alice's birthday (any year)`);
+     * ```
+     */
+    findSameBirthdayAsPerson(personId) {
+        return this.native.findSameBirthdayAsPerson(personId);
+    }
+    /**
+     * Recommend birthday matches for a person
+     *
+     * Returns matches sorted by priority: exact match (same year-month-day) > same month-day.
+     *
+     * @param personId - The person ID to find matches for
+     * @param limit - Maximum number of results (default: 10)
+     * @returns Array of birthday match results with match type
+     *
+     * @example
+     * ```typescript
+     * const matches = social.recommendBirthdayMatches(alice.id, 5);
+     * for (const m of matches) {
+     *   console.log(`${m.person.name}: ${m.birthday} (${m.matchType})`);
+     * }
+     * ```
+     */
+    recommendBirthdayMatches(personId, limit) {
+        return this.native.recommendBirthdayMatches(personId, limit);
+    }
+    /**
+     * Find people with birthdays in the next N days
+     *
+     * @param days - Number of days to look ahead
+     * @returns Array of birthday match results
+     *
+     * @example
+     * ```typescript
+     * const upcoming = social.findUpcomingBirthdays(7);
+     * console.log(`${upcoming.length} birthdays in the next week`);
+     * ```
+     */
+    findUpcomingBirthdays(days) {
+        return this.native.findUpcomingBirthdays(days);
+    }
+    /**
+     * Find people with birthdays today
+     *
+     * @returns Array of person entities whose birthday is today
+     *
+     * @example
+     * ```typescript
+     * const todayBirthdays = social.findTodayBirthdays();
+     * for (const p of todayBirthdays) {
+     *   console.log(`🎂 Happy birthday, ${p.name}!`);
+     * }
+     * ```
+     */
+    findTodayBirthdays() {
+        return this.native.findTodayBirthdays();
+    }
+    /**
+     * Find people with birthdays in a specific month
+     *
+     * @param month - Month number (1-12)
+     * @returns Array of person entities born in that month
+     *
+     * @example
+     * ```typescript
+     * const marchBirthdays = social.findBirthdaysInMonth(3);
+     * console.log(`${marchBirthdays.length} people have March birthdays`);
+     * ```
+     */
+    findBirthdaysInMonth(month) {
+        return this.native.findBirthdaysInMonth(month);
+    }
+    /**
+     * Get birthday statistics
+     *
+     * @returns Statistics object with total count, most common dates, and monthly distribution
+     *
+     * @example
+     * ```typescript
+     * const stats = social.getBirthdayStats();
+     * console.log(`Total with birthday: ${stats.totalWithBirthday}`);
+     * console.log('Most common dates:', stats.mostCommonDates);
+     * console.log('By month:', stats.byMonth);
+     * ```
+     */
+    getBirthdayStats() {
+        return this.native.getBirthdayStats();
+    }
+    /**
+     * Check if two people have the same birthday
+     *
+     * @param personA - First person ID
+     * @param personB - Second person ID
+     * @param exact - If true, compare year+month+day; if false (default), compare month+day only
+     * @returns true if birthdays match
+     *
+     * @example
+     * ```typescript
+     * const sameDay = social.isSameBirthday(alice.id, bob.id);        // month+day only
+     * const sameExact = social.isSameBirthday(alice.id, bob.id, true); // exact date
+     * ```
+     */
+    isSameBirthday(personA, personB, exact) {
+        return this.native.isSameBirthday(personA, personB, exact);
+    }
+    /**
+     * Rebuild birthday index from all person entities
+     *
+     * Useful after bulk imports or data recovery. Scans all persons
+     * and re-indexes their birthday properties.
+     *
+     * @example
+     * ```typescript
+     * // After bulk import of persons with birthday properties
+     * social.rebuildBirthdayIndex();
+     * ```
+     */
+    rebuildBirthdayIndex() {
+        this.native.rebuildBirthdayIndex();
+    }
+    // ========================================================================
+    // Family Tree — Core Relationship Management (Phase-115)
+    // ========================================================================
+    /**
+     * Add parent-child relationship.
+     * Automatically determines father/mother based on parent's gender property.
+     * @param parentId - The parent's entity ID
+     * @param childId - The child's entity ID
+     * @returns The created relation, or null if failed
+     */
+    addParentChild(parentId, childId) {
+        return this.native.addParentChild(parentId, childId) ?? null;
+    }
+    /**
+     * Add spouse relationship (bidirectional).
+     * @param personA - First person's ID
+     * @param personB - Second person's ID
+     */
+    addSpouse(personA, personB) {
+        return this.native.addSpouse(personA, personB) ?? null;
+    }
+    /**
+     * Add sibling relationship (bidirectional).
+     * @param personA - First person's ID
+     * @param personB - Second person's ID
+     * @param halfSibling - Whether this is a half-sibling relationship (default: false)
+     */
+    addSibling(personA, personB, halfSibling = false) {
+        return this.native.addSibling(personA, personB, halfSibling) ?? null;
+    }
+    /**
+     * Remove family relationship between two people.
+     * @returns True if any relationship was removed
+     */
+    removeFamilyRelation(personA, personB) {
+        return this.native.removeFamilyRelation(personA, personB);
+    }
+    /**
+     * Add step-parent to step-child relationship (继父母-继子女).
+     */
+    addStepParentChild(stepParentId, stepChildId) {
+        return this.native.addStepParentChild(stepParentId, stepChildId) ?? null;
+    }
+    /**
+     * Add adoptive parent to adopted child relationship (养父母-养子女).
+     */
+    addAdoptiveParentChild(adoptiveParentId, adoptedChildId) {
+        return this.native.addAdoptiveParentChild(adoptiveParentId, adoptedChildId) ?? null;
+    }
+    /**
+     * Add ex-spouse relationship (前配偶).
+     */
+    addExSpouse(personA, personB) {
+        return this.native.addExSpouse(personA, personB) ?? null;
+    }
+    // ========================================================================
+    // Family Tree — Direct Family Queries (Phase-115)
+    // ========================================================================
+    /** Get parents of a person */
+    getParents(personId) {
+        return this.native.getParents(personId);
+    }
+    /** Get father of a person */
+    getFather(personId) {
+        return this.native.getFather(personId) ?? null;
+    }
+    /** Get mother of a person */
+    getMother(personId) {
+        return this.native.getMother(personId) ?? null;
+    }
+    /** Get children of a person */
+    getChildren(personId) {
+        return this.native.getChildren(personId);
+    }
+    /** Get sons of a person */
+    getSons(personId) {
+        return this.native.getSons(personId);
+    }
+    /** Get daughters of a person */
+    getDaughters(personId) {
+        return this.native.getDaughters(personId);
+    }
+    /** Get current spouse of a person */
+    getSpouse(personId) {
+        return this.native.getSpouse(personId) ?? null;
+    }
+    /** Get all spouses including ex-spouses, with isEx flag */
+    getAllSpouses(personId) {
+        return this.native.getAllSpouses(personId);
+    }
+    // ========================================================================
+    // Family Tree — Step/Adoptive Family Queries (Phase-115)
+    // ========================================================================
+    /** Get step-parents (继父母) */
+    getStepParents(personId) {
+        return this.native.getStepParents(personId);
+    }
+    /** Get step-father (继父) */
+    getStepFather(personId) {
+        return this.native.getStepFather(personId) ?? null;
+    }
+    /** Get step-mother (继母) */
+    getStepMother(personId) {
+        return this.native.getStepMother(personId) ?? null;
+    }
+    /** Get step-children (继子女) */
+    getStepChildren(personId) {
+        return this.native.getStepChildren(personId);
+    }
+    /** Get adoptive parents (养父母) */
+    getAdoptiveParents(personId) {
+        return this.native.getAdoptiveParents(personId);
+    }
+    /** Get adoptive father (养父) */
+    getAdoptiveFather(personId) {
+        return this.native.getAdoptiveFather(personId) ?? null;
+    }
+    /** Get adoptive mother (养母) */
+    getAdoptiveMother(personId) {
+        return this.native.getAdoptiveMother(personId) ?? null;
+    }
+    /** Get adopted children (养子女) */
+    getAdoptedChildren(personId) {
+        return this.native.getAdoptedChildren(personId);
+    }
+    /**
+     * Get all parents with type (biological/step/adoptive).
+     * @returns Array of { person, type } objects
+     */
+    getAllParentsWithType(personId) {
+        return this.native.getAllParentsWithType(personId);
+    }
+    /**
+     * Get all children with type (biological/step/adopted).
+     * @returns Array of { person, type } objects
+     */
+    getAllChildrenWithType(personId) {
+        return this.native.getAllChildrenWithType(personId);
+    }
+    /** Get siblings */
+    getSiblings(personId) {
+        return this.native.getSiblings(personId);
+    }
+    /** Get brothers */
+    getBrothers(personId) {
+        return this.native.getBrothers(personId);
+    }
+    /** Get sisters */
+    getSisters(personId) {
+        return this.native.getSisters(personId);
+    }
+    // ========================================================================
+    // Family Tree — Extended Family Queries (Phase-115)
+    // ========================================================================
+    /**
+     * Get all ancestors (traversing upward).
+     * @param maxGenerations - Maximum generations to traverse (default: 10)
+     */
+    getAncestors(personId, maxGenerations) {
+        return this.native.getAncestors(personId, maxGenerations);
+    }
+    /**
+     * Get all descendants (traversing downward).
+     * @param maxGenerations - Maximum generations to traverse (default: 10)
+     */
+    getDescendants(personId, maxGenerations) {
+        return this.native.getDescendants(personId, maxGenerations);
+    }
+    /** Get grandparents */
+    getGrandparents(personId) {
+        return this.native.getGrandparents(personId);
+    }
+    /** Get paternal grandfather (爷爷) */
+    getPaternalGrandfather(personId) {
+        return this.native.getPaternalGrandfather(personId) ?? null;
+    }
+    /** Get paternal grandmother (奶奶) */
+    getPaternalGrandmother(personId) {
+        return this.native.getPaternalGrandmother(personId) ?? null;
+    }
+    /** Get maternal grandfather (外公/姥爷) */
+    getMaternalGrandfather(personId) {
+        return this.native.getMaternalGrandfather(personId) ?? null;
+    }
+    /** Get maternal grandmother (外婆/姥姥) */
+    getMaternalGrandmother(personId) {
+        return this.native.getMaternalGrandmother(personId) ?? null;
+    }
+    /** Get grandchildren */
+    getGrandchildren(personId) {
+        return this.native.getGrandchildren(personId);
+    }
+    /** Get uncles and aunts (叔伯姑姨舅) */
+    getUnclesAunts(personId) {
+        return this.native.getUnclesAunts(personId);
+    }
+    /** Get paternal uncles (叔叔/伯伯) */
+    getPaternalUncles(personId) {
+        return this.native.getPaternalUncles(personId);
+    }
+    /** Get paternal aunts (姑姑) */
+    getPaternalAunts(personId) {
+        return this.native.getPaternalAunts(personId);
+    }
+    /** Get maternal uncles (舅舅) */
+    getMaternalUncles(personId) {
+        return this.native.getMaternalUncles(personId);
+    }
+    /** Get maternal aunts (姨妈) */
+    getMaternalAunts(personId) {
+        return this.native.getMaternalAunts(personId);
+    }
+    /** Get nephews and nieces (侄子/侄女/外甥/外甥女) */
+    getNephewsNieces(personId) {
+        return this.native.getNephewsNieces(personId);
+    }
+    /** Get cousins (堂/表兄弟姐妹) */
+    getCousins(personId) {
+        return this.native.getCousins(personId);
+    }
+    /** Get paternal cousins (堂兄弟姐妹) */
+    getPaternalCousins(personId) {
+        return this.native.getPaternalCousins(personId);
+    }
+    /** Get maternal cousins (表兄弟姐妹) */
+    getMaternalCousins(personId) {
+        return this.native.getMaternalCousins(personId);
+    }
+    // ========================================================================
+    // Family Tree — In-law Queries (Phase-115)
+    // ========================================================================
+    /** Get father-in-law (公公/岳父) */
+    getFatherInLaw(personId) {
+        return this.native.getFatherInLaw(personId) ?? null;
+    }
+    /** Get mother-in-law (婆婆/岳母) */
+    getMotherInLaw(personId) {
+        return this.native.getMotherInLaw(personId) ?? null;
+    }
+    /** Get siblings-in-law */
+    getSiblingsInLaw(personId) {
+        return this.native.getSiblingsInLaw(personId);
+    }
+    /** Get children-in-law (儿媳/女婿) */
+    getChildrenInLaw(personId) {
+        return this.native.getChildrenInLaw(personId);
+    }
+    // ========================================================================
+    // Family Tree — Relationship Calculation (Phase-115)
+    // ========================================================================
+    /**
+     * Calculate the family relationship between two people.
+     * Returns the full path including Chinese relationship title,
+     * generation difference, and blood distance.
+     * @param fromId - Starting person's ID
+     * @param toId - Ending person's ID
+     */
+    calculateFamilyRelationship(fromId, toId) {
+        return this.native.calculateFamilyRelationship(fromId, toId) ?? null;
+    }
+    /**
+     * Get the Chinese relationship title between two people.
+     * @example
+     * ```typescript
+     * const title = social.getRelationshipTitle(child.id, father.id);
+     * // Returns: "父亲"
+     * ```
+     */
+    getRelationshipTitle(fromId, toId) {
+        return this.native.getRelationshipTitle(fromId, toId) ?? null;
+    }
+    /** Find the closest common ancestor of two people */
+    findCommonAncestor(personA, personB) {
+        return this.native.findCommonAncestor(personA, personB) ?? null;
+    }
+    /**
+     * Calculate the blood distance between two people.
+     * Blood distance = number of parent-child links through common ancestor.
+     */
+    calculateBloodDistance(personA, personB) {
+        return this.native.calculateBloodDistance(personA, personB) ?? null;
+    }
+    /** Check if two people are direct blood relatives (ancestor/descendant) */
+    isDirectBloodRelative(personA, personB) {
+        return this.native.isDirectBloodRelative(personA, personB);
+    }
+    // ========================================================================
+    // Family Tree — Tree Construction (Phase-115)
+    // ========================================================================
+    /**
+     * Build a family tree centered on a person.
+     * @param personId - Center person's ID
+     * @param generationsUp - Generations to traverse upward (default: 3)
+     * @param generationsDown - Generations to traverse downward (default: 3)
+     */
+    buildFamilyTree(personId, generationsUp, generationsDown) {
+        return this.native.buildFamilyTree(personId, generationsUp, generationsDown) ?? null;
+    }
+    /**
+     * Get generation number of a person relative to a root.
+     * 0 = same as root, positive = younger, negative = older.
+     */
+    getGeneration(personId, rootId) {
+        return this.native.getGeneration(personId, rootId) ?? null;
+    }
+    /** Get all people in the same generation (siblings, cousins, spouse) */
+    getSameGeneration(personId) {
+        return this.native.getSameGeneration(personId);
+    }
+    // ========================================================================
+    // Family Tree — Lineage Queries (Phase-115)
+    // ========================================================================
+    /**
+     * Get paternal lineage (父系血统): father → grandfather → great-grandfather → ...
+     * @param maxGenerations - Maximum generations to trace (default: 10)
+     */
+    getPaternalLineage(personId, maxGenerations) {
+        return this.native.getPaternalLineage(personId, maxGenerations);
+    }
+    /**
+     * Get maternal lineage (母系血统): mother → grandmother → great-grandmother → ...
+     * @param maxGenerations - Maximum generations to trace (default: 10)
+     */
+    getMaternalLineage(personId, maxGenerations) {
+        return this.native.getMaternalLineage(personId, maxGenerations);
+    }
+    /** Get same surname relatives (同姓族人) */
+    getSameSurnameRelatives(personId) {
+        return this.native.getSameSurnameRelatives(personId);
+    }
+    /**
+     * Get paternal clan members (父系宗族成员).
+     * Traditional Chinese "宗族" — all connected through paternal line.
+     * @param maxGenerations - Maximum generations to include (default: 5)
+     */
+    getPaternalClan(personId, maxGenerations) {
+        return this.native.getPaternalClan(personId, maxGenerations);
+    }
+    // ========================================================================
+    // Family Tree — Statistics & Gender (Phase-115)
+    // ========================================================================
+    /**
+     * Get family statistics for a tree rooted at the given person.
+     * @returns { total_members, total_generations, male_count, female_count, ... }
+     */
+    getFamilyStats(rootId) {
+        return this.native.getFamilyStats(rootId) ?? null;
+    }
+    /**
+     * Set the gender of a person.
+     * @param gender - 'male', 'female', or 'unknown'
+     */
+    setPersonGender(personId, gender) {
+        return this.native.setPersonGender(personId, gender);
+    }
+    // ========================================================================
     // Generic Entity Operations
     // ========================================================================
     /**
@@ -1361,6 +1902,140 @@ class SocialGraphV2 {
     hybridSearch(embedding, textQuery, k, entityTypeFilter) {
         return this.native.hybridSearch(embedding, textQuery, k, entityTypeFilter);
     }
+    /**
+     * Get the embedding dimension used by the HNSW index.
+     * Returns null if vector search is not enabled.
+     */
+    vectorDimension() {
+        return this.native.vectorDimension() ?? null;
+    }
+    /**
+     * Get the current embedding model identifier (Phase-110).
+     * Returns the model ID (e.g., "all-MiniLM-L6-v2") or null if not set.
+     */
+    vectorModelId() {
+        return this.native.vectorModelId() ?? null;
+    }
+    // ========================================================================
+    // Phase-111: Full-Text Search (Tantivy BM25)
+    // ========================================================================
+    /**
+     * Check if full-text search (Tantivy) is enabled on this store.
+     */
+    hasTextSearch() {
+        return this.native.hasTextSearch();
+    }
+    /**
+     * Get the number of documents in the Tantivy index.
+     * Returns null if text search is not enabled.
+     */
+    textSearchDocCount() {
+        return this.native.textSearchDocCount() ?? null;
+    }
+    /**
+     * Full-text search on entity content using Tantivy BM25.
+     *
+     * Searches entity name, content property, and other indexed string properties.
+     * Supports both Chinese (jieba-rs) and English tokenization.
+     *
+     * @param query - Search query text (supports Chinese and English)
+     * @param entityTypeFilter - Optional: only return entities of this type
+     * @param topK - Number of results to return (default: 10)
+     * @returns Array of TextSearchHit sorted by BM25 score
+     *
+     * @example
+     * ```typescript
+     * const results = social.searchEntitiesByText('社交图谱', 'document', 20);
+     * for (const hit of results) {
+     *   console.log(`${hit.entityId}: score=${hit.score}, snippet=${hit.snippet}`);
+     * }
+     * ```
+     */
+    searchEntitiesByText(query, entityTypeFilter, topK) {
+        return this.native.searchEntitiesByText(query, entityTypeFilter, topK);
+    }
+    /**
+     * Hybrid search combining vector similarity (HNSW) + full-text (Tantivy BM25)
+     * with Reciprocal Rank Fusion (RRF).
+     *
+     * This method differs from `hybridSearch` by using Tantivy (BM25 + jieba)
+     * for the text component instead of simple substring matching on entity attributes.
+     *
+     * @param embedding - Optional query vector (pass null for text-only search)
+     * @param textQuery - Optional BM25 search text (pass null for vector-only search)
+     * @param entityTypeFilter - Optional: filter by entity type
+     * @param topK - Number of results to return (default: 10)
+     * @param rrfK - RRF constant (default: 60.0, higher = less weight to rank position)
+     * @returns Array of VectorSearchHit sorted by fused RRF score
+     *
+     * @example
+     * ```typescript
+     * // Vector + BM25 hybrid
+     * const results = social.hybridSearchTantivy(queryVec, '记忆树搜索', 'document', 10);
+     *
+     * // Text-only via Tantivy BM25 (pass null for embedding)
+     * const textResults = social.hybridSearchTantivy(null, '架构决策', undefined, 10);
+     *
+     * // Vector-only (pass null for textQuery)
+     * const vecResults = social.hybridSearchTantivy(queryVec, null, undefined, 10);
+     * ```
+     */
+    hybridSearchTantivy(embedding, textQuery, entityTypeFilter, topK, rrfK) {
+        return this.native.hybridSearchTantivy(embedding ?? undefined, textQuery ?? undefined, entityTypeFilter, topK, rrfK);
+    }
+    /**
+     * Manually commit the Tantivy text index.
+     * Only needed when `autoCommit` is disabled in TextSearchConfig.
+     */
+    textSearchCommit() {
+        this.native.textSearchCommit();
+    }
+    /**
+     * Hot-reload user dictionary for jieba Chinese tokenizer.
+     *
+     * Loads a new custom dictionary without restarting.
+     * File format: one entry per line — `词语 词频 词性` (e.g., `SocialGraphV2 5 n`)
+     *
+     * @param dictPath - Path to the user dictionary file
+     */
+    reloadUserDict(dictPath) {
+        this.native.reloadUserDict(dictPath);
+    }
+    /**
+     * Hot-reload synonym map for query expansion.
+     *
+     * JSON format: `{ "entries": [{ "term": "数据库", "synonyms": ["DB"], "bidirectional": true }] }`
+     *
+     * @param synonymPath - Path to the synonym map JSON file
+     * @returns Number of synonym entries loaded
+     */
+    reloadSynonyms(synonymPath) {
+        return this.native.reloadSynonyms(synonymPath);
+    }
+    // ========================================================================
+    // Phase-97: Entity Type Queries
+    // ========================================================================
+    /**
+     * Get all unique entity types in the graph.
+     *
+     * @example
+     * ```typescript
+     * const types = social.getEntityTypes();
+     * // ["person", "tag", "article", "category", ...]
+     * ```
+     */
+    getEntityTypes() {
+        return this.native.getEntityTypes();
+    }
+    /**
+     * Count entities by type (optimized — reads index only, no entity loading).
+     *
+     * @param entityType - Entity type to count
+     * @returns Number of entities of the given type
+     */
+    countEntitiesByType(entityType) {
+        return this.native.countEntitiesByType(entityType);
+    }
     // ========================================================================
     // Phase-107: Graph Traversal, Mutations & DynamicNode
     // ========================================================================