@memberjunction/record-graph 0.0.0 → 6.2.0-edge.2

package/dist/DependencyGraphWalker.js

@@ -0,0 +1,847 @@
+import { CompositeKey, Metadata, RunView, LogError, LogStatus, } from '@memberjunction/core';
+import { EscapeSQLString, NormalizeUUID, UUIDsEqual } from '@memberjunction/global';
+import { BuildCompositeKeyFromRecord } from './keys.js';
+import { SortNodesTopologically } from './sort.js';
+import { SYSTEM_FK_SKIP_PATTERNS } from './constants.js';
+/**
+ * Walks a record's relationship graph to discover all dependent and referenced records.
+ *
+ * Traversal rules:
+ * - Reverse walk: follows curated One-To-Many relationships (where child points to parent).
+ *   Recurses with 'full' mode (both reverse + forward).
+ * - Forward walk: follows foreign keys on the parent (where parent points to another entity).
+ *   Recurses with 'forward-only' mode — targets do NOT discover their own reverse children,
+ *   preventing graph explosion from shared/hub entities.
+ * - Subtypes: follows IS-A inheritance if IncludeSubtypes is true.
+ * - Hierarchies: follows self-referencing hierarchy FKs if FollowHierarchies is true.
+ * - Soft links: follows inbound polymorphic EntityID/RecordID links if IncludeSoftLinks is true.
+ * - Non-curated inbound FKs: discovers non-curated inbound FKs if ListNonCuratedInbound is true.
+ * - EdgePolicy: callers can supply an EdgePolicy callback to dictate Deep / Reference / Skip per edge.
+ * - Cycle prevention: uses ancestorStack (entity types) to prevent backtracking and a global visited set (records).
+ */
+export class DependencyGraphWalker {
+    constructor(provider) {
+        /** Cache: entityID → reverse relationships from EntityRelationship metadata */
+        this.reverseRelCache = new Map();
+        /** Cache: entityID → forward FK references from field metadata */
+        this.forwardRefCache = new Map();
+        this._provider = provider;
+    }
+    /** Returns the active provider — explicit override if set, otherwise the global default. */
+    get ProviderToUse() {
+        return (this._provider ?? Metadata.Provider);
+    }
+    // =========================================================================
+    // Public API
+    // =========================================================================
+    /**
+     * Walk from a root record through its relationships, building a tree of
+     * all records that should be included in a version label or clone plan.
+     *
+     * @param entityName - The starting entity name
+     * @param recordKey  - The starting record's primary key
+     * @param options    - Controls depth, filtering, policies, etc.
+     * @param contextUser - Server-side user context
+     * @returns The root DependencyNode with all descendants populated
+     */
+    async WalkDependents(entityName, recordKey, options, contextUser) {
+        const md = this.ProviderToUse;
+        const entityInfo = md.EntityByName(entityName);
+        if (!entityInfo) {
+            throw new Error(`Entity '${entityName}' not found in metadata`);
+        }
+        const resolvedOptions = this.resolveDefaults(options);
+        const visited = new Set();
+        const ancestorStack = new Set();
+        const stats = this.createEmptyStats();
+        this.reverseRelCache.clear();
+        this.forwardRefCache.clear();
+        const rootData = await this.loadRecordData(entityInfo, recordKey, contextUser);
+        const rootNode = {
+            EntityName: entityName,
+            EntityInfo: entityInfo,
+            RecordKey: recordKey,
+            RecordID: recordKey.ToConcatenatedString(),
+            RecordData: rootData,
+            Relationship: null,
+            Children: [],
+            Depth: 0,
+            DiscoveringEdge: null,
+        };
+        // Mark root as visited and push its entity type onto the ancestor stack
+        visited.add(this.visitKey(entityInfo.Name, rootNode.RecordID));
+        ancestorStack.add(entityInfo.Name);
+        this.incrementEntityCount(stats, entityInfo.Name);
+        // Root always gets full discovery mode (both reverse + forward); walkChildren also walks
+        // the root's IS-A subtypes when IncludeSubtypes is on.
+        await this.walkChildren(rootNode, 'full', resolvedOptions, visited, ancestorStack, stats, contextUser);
+        // Pop root (cleanup)
+        ancestorStack.delete(entityInfo.Name);
+        this.logWalkSummary(entityName, resolvedOptions, stats);
+        return rootNode;
+    }
+    /**
+     * Flatten a dependency tree into a topologically sorted list.
+     * Parents appear before their children, ensuring safe restore or clone execution ordering.
+     */
+    FlattenTopological(root) {
+        return SortNodesTopologically(root);
+    }
+    // =========================================================================
+    // Core Walk Logic
+    // =========================================================================
+    /**
+     * Recursively discover and attach child nodes for a given parent node.
+     */
+    async walkChildren(parentNode, discoveryMode, options, visited, ancestorStack, stats, contextUser) {
+        if (parentNode.Depth >= options.MaxDepth) {
+            return;
+        }
+        // Reverse walk: only when in full mode (root or reverse-discovered nodes)
+        if (discoveryMode === 'full') {
+            await this.walkReverseRelationships(parentNode, options, visited, ancestorStack, stats, contextUser);
+            if (options.ListNonCuratedInbound) {
+                await this.walkNonCuratedInbound(parentNode, options, visited, ancestorStack, stats, contextUser);
+            }
+            if (options.IncludeSoftLinks) {
+                await this.walkSoftLinks(parentNode, options, visited, ancestorStack, stats, contextUser);
+            }
+        }
+        else {
+            stats.ForwardOnlySuppressions++;
+        }
+        // Forward walk: always performed regardless of discovery mode
+        await this.walkForwardReferences(parentNode, options, visited, ancestorStack, stats, contextUser);
+        // Subtypes walk: if enabled, discover IS-A rows
+        if (options.IncludeSubtypes) {
+            await this.walkSubtypes(parentNode, options, visited, ancestorStack, stats, contextUser);
+        }
+    }
+    // =========================================================================
+    // Reverse Walking (EntityRelationship-driven)
+    // =========================================================================
+    /**
+     * Walk reverse relationships: for each EntityRelationship on the parent
+     * entity, load matching child records and recurse into them.
+     */
+    async walkReverseRelationships(parentNode, options, visited, ancestorStack, stats, contextUser) {
+        const relationships = this.discoverReverseRelationships(parentNode.EntityInfo, options);
+        for (const rel of relationships) {
+            const isHierarchyRel = UUIDsEqual(rel.ChildEntityInfo.ID, parentNode.EntityInfo.ID);
+            if (isHierarchyRel && !options.FollowHierarchies) {
+                continue;
+            }
+            // Ancestor check: skip if the child entity type is on our current path (unless allowed hierarchy recursion)
+            if (ancestorStack.has(rel.ChildEntityInfo.Name) && !(isHierarchyRel && options.FollowHierarchies)) {
+                stats.AncestorSkips++;
+                continue;
+            }
+            if (this.shouldSkipEntity(rel.ChildEntityInfo.Name, options)) {
+                continue;
+            }
+            const edgeKind = isHierarchyRel ? 'Hierarchy' : (rel.IsCollection ? 'Collection' : 'Relationship');
+            // Check edge policy before loading if policy is configured
+            const edgeCandidate = {
+                Kind: edgeKind,
+                SourceEntityName: parentNode.EntityName,
+                SourceKey: parentNode.RecordKey,
+                SourceRecordData: parentNode.RecordData,
+                TargetEntityName: rel.ChildEntityInfo.Name,
+                JoinField: rel.ChildJoinField,
+                Relationship: rel.RelationshipInfo,
+                CollectionName: rel.CollectionName,
+                IsSoftLink: false,
+                Depth: parentNode.Depth + 1,
+                HierarchyDirection: isHierarchyRel ? 'Down' : undefined,
+            };
+            const edgeDecision = options.EdgePolicy ? options.EdgePolicy(edgeCandidate) : 'Deep';
+            if (edgeDecision === 'Skip') {
+                continue;
+            }
+            const childRecords = await this.loadChildRecords(parentNode, rel, options, contextUser, (message) => options.OnLoadFailure?.({ Edge: edgeCandidate, Decision: edgeDecision, Message: message }));
+            for (const childData of childRecords) {
+                const childKey = BuildCompositeKeyFromRecord(rel.ChildEntityInfo, childData);
+                const discoveringEdge = {
+                    Kind: edgeKind,
+                    FromKey: this.visitKey(parentNode.EntityName, parentNode.RecordID),
+                    ToKey: this.visitKey(rel.ChildEntityInfo.Name, childKey.ToConcatenatedString()),
+                    SourceEntityName: parentNode.EntityName,
+                    TargetEntityName: rel.ChildEntityInfo.Name,
+                    JoinField: rel.ChildJoinField,
+                    Relationship: rel.RelationshipInfo,
+                    CollectionName: rel.CollectionName,
+                    IsSoftLink: false,
+                };
+                // Re-evaluate EdgePolicy per-record if candidate target key is known
+                let decision = 'Deep';
+                if (options.EdgePolicy) {
+                    const candidate = {
+                        Kind: edgeKind,
+                        SourceEntityName: parentNode.EntityName,
+                        SourceKey: parentNode.RecordKey,
+                        SourceRecordData: parentNode.RecordData,
+                        TargetEntityName: rel.ChildEntityInfo.Name,
+                        TargetKey: childKey,
+                        JoinField: rel.ChildJoinField,
+                        Relationship: rel.RelationshipInfo,
+                        CollectionName: rel.CollectionName,
+                        IsSoftLink: false,
+                        Depth: parentNode.Depth + 1,
+                        HierarchyDirection: isHierarchyRel ? 'Down' : undefined,
+                    };
+                    decision = options.EdgePolicy(candidate);
+                    if (decision === 'Skip')
+                        continue;
+                }
+                const childNode = this.registerNode(rel.ChildEntityInfo, childData, rel.RelationshipInfo, parentNode, visited, stats, discoveringEdge);
+                if (!childNode)
+                    continue;
+                if (decision === 'Deep') {
+                    // Push child entity type, recurse with FULL mode, then pop
+                    const alreadyInStack = ancestorStack.has(rel.ChildEntityInfo.Name);
+                    if (!alreadyInStack) {
+                        ancestorStack.add(rel.ChildEntityInfo.Name);
+                    }
+                    await this.walkChildren(childNode, 'full', options, visited, ancestorStack, stats, contextUser);
+                    if (!alreadyInStack) {
+                        ancestorStack.delete(rel.ChildEntityInfo.Name);
+                    }
+                }
+            }
+        }
+    }
+    // =========================================================================
+    // Inbound Non-Curated FK Walking
+    // =========================================================================
+    /**
+     * Discovers inbound foreign keys that are not registered as curated EntityRelationships.
+     * Evaluated when ListNonCuratedInbound is true.
+     */
+    async walkNonCuratedInbound(parentNode, options, visited, ancestorStack, stats, contextUser) {
+        if (!options.EdgePolicy)
+            return; // Non-curated inbound edges require an explicit policy
+        const md = this.ProviderToUse;
+        const parentEntity = parentNode.EntityInfo;
+        const parentKeyField = parentEntity.FirstPrimaryKey.Name; // first-pk-ok: foreign keys target single-column primary keys
+        const parentKeyValue = parentNode.RecordData[parentKeyField];
+        if (parentKeyValue == null)
+            return;
+        // Curated child entity IDs to skip
+        const curatedChildEntityIds = new Set(parentEntity.RelatedEntities.map(r => NormalizeUUID(r.RelatedEntityID)));
+        for (const entity of md.Entities) {
+            if (options.RequireTrackRecordChanges && !entity.TrackRecordChanges)
+                continue;
+            if (this.shouldSkipEntity(entity.Name, options))
+                continue;
+            if (curatedChildEntityIds.has(NormalizeUUID(entity.ID)))
+                continue;
+            for (const field of entity.Fields) {
+                if (!field.RelatedEntityID || !UUIDsEqual(field.RelatedEntityID, parentEntity.ID))
+                    continue;
+                if (this.isSystemFKField(field.Name))
+                    continue;
+                const candidate = {
+                    Kind: 'InboundFK',
+                    SourceEntityName: parentNode.EntityName,
+                    SourceKey: parentNode.RecordKey,
+                    SourceRecordData: parentNode.RecordData,
+                    TargetEntityName: entity.Name,
+                    JoinField: field.Name,
+                    Relationship: null,
+                    IsSoftLink: false,
+                    Depth: parentNode.Depth + 1,
+                };
+                const decision = options.EdgePolicy(candidate);
+                if (decision === 'Skip')
+                    continue;
+                // Load records matching inbound FK
+                const filter = `[${field.Name}] = '${EscapeSQLString(String(parentKeyValue))}'` +
+                    (!options.IncludeDeleted && this.entityHasSoftDelete(entity) ? ' AND __mj_DeletedAt IS NULL' : '');
+                try {
+                    const rv = RunView.FromMetadataProvider(this.ProviderToUse);
+                    const result = await rv.RunView({
+                        EntityName: entity.Name,
+                        ExtraFilter: filter,
+                        ResultType: 'simple',
+                    }, contextUser);
+                    if (!result.Success) {
+                        options.OnLoadFailure?.({ Edge: candidate, Decision: decision, Message: result.ErrorMessage || 'the query failed' });
+                        continue;
+                    }
+                    for (const row of result.Results) {
+                        const rowKey = BuildCompositeKeyFromRecord(entity, row);
+                        const discoveringEdge = {
+                            Kind: 'InboundFK',
+                            FromKey: this.visitKey(parentNode.EntityName, parentNode.RecordID),
+                            ToKey: this.visitKey(entity.Name, rowKey.ToConcatenatedString()),
+                            SourceEntityName: parentNode.EntityName,
+                            TargetEntityName: entity.Name,
+                            JoinField: field.Name,
+                            Relationship: null,
+                            IsSoftLink: false,
+                        };
+                        const childNode = this.registerNode(entity, row, null, parentNode, visited, stats, discoveringEdge);
+                        if (!childNode)
+                            continue;
+                        if (decision === 'Deep') {
+                            ancestorStack.add(entity.Name);
+                            await this.walkChildren(childNode, 'full', options, visited, ancestorStack, stats, contextUser);
+                            ancestorStack.delete(entity.Name);
+                        }
+                    }
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    LogError(`DependencyGraphWalker: Error loading inbound FK records for ${entity.Name}: ${msg}`);
+                    options.OnLoadFailure?.({ Edge: candidate, Decision: decision, Message: msg });
+                }
+            }
+        }
+    }
+    // =========================================================================
+    // Soft Link Walking
+    // =========================================================================
+    /**
+     * Discovers records pointing to the parent via polymorphic EntityID/RecordID soft links.
+     */
+    async walkSoftLinks(parentNode, options, visited, ancestorStack, stats, contextUser) {
+        const md = this.ProviderToUse;
+        const parentEntity = parentNode.EntityInfo;
+        for (const entity of md.Entities) {
+            if (options.RequireTrackRecordChanges && !entity.TrackRecordChanges)
+                continue;
+            if (this.shouldSkipEntity(entity.Name, options))
+                continue;
+            // Look for fields declared with EntityIDFieldName
+            for (const field of entity.Fields) {
+                if (!field.EntityIDFieldName)
+                    continue;
+                const candidate = {
+                    Kind: 'SoftLink',
+                    SourceEntityName: parentNode.EntityName,
+                    SourceKey: parentNode.RecordKey,
+                    SourceRecordData: parentNode.RecordData,
+                    TargetEntityName: entity.Name,
+                    JoinField: field.Name,
+                    Relationship: null,
+                    IsSoftLink: true,
+                    EntityIDFieldName: field.EntityIDFieldName,
+                    Depth: parentNode.Depth + 1,
+                };
+                const decision = options.EdgePolicy ? options.EdgePolicy(candidate) : 'Skip';
+                if (decision === 'Skip')
+                    continue;
+                // Build query: EntityID discriminator match and RecordID match
+                // Soft links store either the full record-id ("ID|abc") or, commonly for a single
+                // key column, the bare value ("abc"); match both.
+                const recordIDValue = parentNode.RecordKey.ToRecordID();
+                const bareIDValue = parentNode.RecordKey.ToCompactURLSegment();
+                const filter = `([${field.EntityIDFieldName}] = '${EscapeSQLString(parentEntity.ID)}' OR [${field.EntityIDFieldName}] = '${EscapeSQLString(parentEntity.Name)}') ` +
+                    `AND ([${field.Name}] = '${EscapeSQLString(recordIDValue)}' OR [${field.Name}] = '${EscapeSQLString(bareIDValue)}')` +
+                    (!options.IncludeDeleted && this.entityHasSoftDelete(entity) ? ' AND __mj_DeletedAt IS NULL' : '');
+                try {
+                    const rv = RunView.FromMetadataProvider(this.ProviderToUse);
+                    const result = await rv.RunView({
+                        EntityName: entity.Name,
+                        ExtraFilter: filter,
+                        ResultType: 'simple',
+                    }, contextUser);
+                    if (!result.Success) {
+                        options.OnLoadFailure?.({ Edge: candidate, Decision: decision, Message: result.ErrorMessage || 'the query failed' });
+                        continue;
+                    }
+                    for (const row of result.Results) {
+                        const rowKey = BuildCompositeKeyFromRecord(entity, row);
+                        const discoveringEdge = {
+                            Kind: 'SoftLink',
+                            FromKey: this.visitKey(parentNode.EntityName, parentNode.RecordID),
+                            ToKey: this.visitKey(entity.Name, rowKey.ToConcatenatedString()),
+                            SourceEntityName: parentNode.EntityName,
+                            TargetEntityName: entity.Name,
+                            JoinField: field.Name,
+                            Relationship: null,
+                            IsSoftLink: true,
+                            EntityIDFieldName: field.EntityIDFieldName,
+                        };
+                        const childNode = this.registerNode(entity, row, null, parentNode, visited, stats, discoveringEdge);
+                        if (!childNode)
+                            continue;
+                        if (decision === 'Deep') {
+                            ancestorStack.add(entity.Name);
+                            await this.walkChildren(childNode, 'full', options, visited, ancestorStack, stats, contextUser);
+                            ancestorStack.delete(entity.Name);
+                        }
+                    }
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    LogError(`DependencyGraphWalker: Error loading soft link records for ${entity.Name}: ${msg}`);
+                    options.OnLoadFailure?.({ Edge: candidate, Decision: decision, Message: msg });
+                }
+            }
+        }
+    }
+    // =========================================================================
+    // Subtypes Walking (IS-A)
+    // =========================================================================
+    /**
+     * Discover and attach IS-A subtype rows for a given parent record.
+     */
+    async walkSubtypes(parentNode, options, visited, ancestorStack, stats, contextUser) {
+        const md = this.ProviderToUse;
+        if (!md.FindISAChildEntities)
+            return;
+        try {
+            // IS-A tables share one single-column key, and the provider matches on its bare value
+            // (not the "ID|<guid>" record-id string, which errors on a UUID column).
+            const pkValue = parentNode.RecordKey.KeyValuePairs[0]?.Value;
+            if (pkValue === null || pkValue === undefined)
+                return;
+            const subtypes = await md.FindISAChildEntities(parentNode.EntityInfo, String(pkValue), contextUser);
+            for (const subtype of subtypes) {
+                const childEntityInfo = md.EntityByName(subtype.ChildEntityName);
+                if (!childEntityInfo)
+                    continue;
+                if (options.RequireTrackRecordChanges && !childEntityInfo.TrackRecordChanges)
+                    continue;
+                if (this.shouldSkipEntity(childEntityInfo.Name, options))
+                    continue;
+                const candidate = {
+                    Kind: 'IsASubtype',
+                    SourceEntityName: parentNode.EntityName,
+                    SourceKey: parentNode.RecordKey,
+                    SourceRecordData: parentNode.RecordData,
+                    TargetEntityName: childEntityInfo.Name,
+                    TargetKey: parentNode.RecordKey,
+                    JoinField: childEntityInfo.FirstPrimaryKey.Name, // first-pk-ok: IS-A subtype shares the parent's single-column key
+                    Relationship: null,
+                    IsSoftLink: false,
+                    Depth: parentNode.Depth + 1,
+                };
+                const decision = options.EdgePolicy ? options.EdgePolicy(candidate) : 'Deep';
+                if (decision === 'Skip')
+                    continue;
+                // Load subtype record using the same primary key value
+                const childData = await this.loadRecordData(childEntityInfo, parentNode.RecordKey, contextUser);
+                if (!childData || Object.keys(childData).length === 0)
+                    continue;
+                const discoveringEdge = {
+                    Kind: 'IsASubtype',
+                    FromKey: this.visitKey(parentNode.EntityName, parentNode.RecordID),
+                    ToKey: this.visitKey(childEntityInfo.Name, parentNode.RecordID),
+                    SourceEntityName: parentNode.EntityName,
+                    TargetEntityName: childEntityInfo.Name,
+                    JoinField: childEntityInfo.FirstPrimaryKey.Name, // first-pk-ok: IS-A subtype shares the parent's single-column key
+                    Relationship: null,
+                    IsSoftLink: false,
+                };
+                const childNode = this.registerNode(childEntityInfo, childData, null, parentNode, visited, stats, discoveringEdge, true);
+                if (!childNode)
+                    continue;
+                if (decision === 'Deep') {
+                    ancestorStack.add(childEntityInfo.Name);
+                    await this.walkChildren(childNode, 'full', options, visited, ancestorStack, stats, contextUser);
+                    ancestorStack.delete(childEntityInfo.Name);
+                }
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            LogError(`DependencyGraphWalker: Error finding IS-A child entities for ${parentNode.EntityName}: ${msg}`);
+        }
+    }
+    // =========================================================================
+    // Forward Walking (FK field-driven)
+    // =========================================================================
+    /**
+     * Walk forward FK references: for each FK field on the parent entity that
+     * points to another entity, load the referenced record and recurse.
+     */
+    async walkForwardReferences(parentNode, options, visited, ancestorStack, stats, contextUser) {
+        const forwardRefs = this.discoverForwardReferences(parentNode.EntityInfo, options);
+        for (const ref of forwardRefs) {
+            // Self-pointer check
+            if (ref.IsSelf) {
+                if (ref.IsHierarchy && options.FollowHierarchies) {
+                    // Follow hierarchy edge
+                    const fkValue = parentNode.RecordData[ref.FKFieldName];
+                    if (fkValue == null)
+                        continue;
+                    const targetKey = new CompositeKey([{
+                            FieldName: ref.TargetKeyField,
+                            Value: fkValue,
+                        }]);
+                    const candidate = {
+                        Kind: 'Hierarchy',
+                        SourceEntityName: parentNode.EntityName,
+                        SourceKey: parentNode.RecordKey,
+                        SourceRecordData: parentNode.RecordData,
+                        TargetEntityName: ref.TargetEntityInfo.Name,
+                        TargetKey: targetKey,
+                        JoinField: ref.FKFieldName,
+                        Relationship: null,
+                        IsSoftLink: false,
+                        Depth: parentNode.Depth + 1,
+                        HierarchyDirection: 'Up',
+                    };
+                    const decision = options.EdgePolicy ? options.EdgePolicy(candidate) : 'Deep';
+                    if (decision === 'Skip')
+                        continue;
+                    const vKey = this.visitKey(ref.TargetEntityInfo.Name, targetKey.ToConcatenatedString());
+                    if (visited.has(vKey)) {
+                        stats.VisitedSkips++;
+                        continue;
+                    }
+                    const targetData = await this.loadRecordData(ref.TargetEntityInfo, targetKey, contextUser);
+                    if (!targetData || Object.keys(targetData).length === 0)
+                        continue;
+                    const discoveringEdge = {
+                        Kind: 'Hierarchy',
+                        FromKey: this.visitKey(parentNode.EntityName, parentNode.RecordID),
+                        ToKey: vKey,
+                        SourceEntityName: parentNode.EntityName,
+                        TargetEntityName: ref.TargetEntityInfo.Name,
+                        JoinField: ref.FKFieldName,
+                        Relationship: null,
+                        IsSoftLink: false,
+                    };
+                    const targetNode = this.registerNode(ref.TargetEntityInfo, targetData, null, parentNode, visited, stats, discoveringEdge);
+                    if (!targetNode)
+                        continue;
+                    if (decision === 'Deep') {
+                        await this.walkChildren(targetNode, 'full', options, visited, ancestorStack, stats, contextUser);
+                    }
+                }
+                // Plain self pointers are never followed automatically
+                continue;
+            }
+            // Ancestor check: skip if target entity type is on our current path
+            if (ancestorStack.has(ref.TargetEntityInfo.Name)) {
+                stats.AncestorSkips++;
+                continue;
+            }
+            if (this.shouldSkipEntity(ref.TargetEntityInfo.Name, options)) {
+                continue;
+            }
+            // Read the FK value from the record data
+            const fkValue = parentNode.RecordData[ref.FKFieldName];
+            if (fkValue == null)
+                continue;
+            const targetKey = new CompositeKey([{
+                    FieldName: ref.TargetKeyField,
+                    Value: fkValue,
+                }]);
+            const edgeKind = ref.IsEmbedded ? 'Embedded' : 'ForwardFK';
+            // Check edge policy before loading
+            let decision = ref.IsEmbedded ? 'Deep' : 'Reference';
+            if (options.EdgePolicy) {
+                const candidate = {
+                    Kind: edgeKind,
+                    SourceEntityName: parentNode.EntityName,
+                    SourceKey: parentNode.RecordKey,
+                    SourceRecordData: parentNode.RecordData,
+                    TargetEntityName: ref.TargetEntityInfo.Name,
+                    TargetKey: targetKey,
+                    JoinField: ref.FKFieldName,
+                    Relationship: null,
+                    IsSoftLink: false,
+                    Depth: parentNode.Depth + 1,
+                };
+                decision = options.EdgePolicy(candidate);
+                if (decision === 'Skip')
+                    continue;
+            }
+            // Skip if we've already visited this specific record
+            const vKey = this.visitKey(ref.TargetEntityInfo.Name, targetKey.ToConcatenatedString());
+            if (visited.has(vKey)) {
+                stats.VisitedSkips++;
+                continue;
+            }
+            const targetData = await this.loadRecordData(ref.TargetEntityInfo, targetKey, contextUser);
+            if (!targetData || Object.keys(targetData).length === 0)
+                continue;
+            const discoveringEdge = {
+                Kind: edgeKind,
+                FromKey: this.visitKey(parentNode.EntityName, parentNode.RecordID),
+                ToKey: vKey,
+                SourceEntityName: parentNode.EntityName,
+                TargetEntityName: ref.TargetEntityInfo.Name,
+                JoinField: ref.FKFieldName,
+                Relationship: null,
+                IsSoftLink: false,
+            };
+            const targetNode = this.registerNode(ref.TargetEntityInfo, targetData, null, parentNode, visited, stats, discoveringEdge);
+            if (!targetNode)
+                continue;
+            // Recurse based on policy decision:
+            // 'Deep' recurses with full mode; 'Reference' recurses with forward-only mode
+            const nextMode = decision === 'Deep' ? 'full' : 'forward-only';
+            ancestorStack.add(ref.TargetEntityInfo.Name);
+            await this.walkChildren(targetNode, nextMode, options, visited, ancestorStack, stats, contextUser);
+            ancestorStack.delete(ref.TargetEntityInfo.Name);
+        }
+    }
+    // =========================================================================
+    // Relationship Discovery
+    // =========================================================================
+    /**
+     * Discover reverse relationships for an entity using EntityRelationship metadata.
+     */
+    discoverReverseRelationships(parentEntity, options) {
+        const cached = this.reverseRelCache.get(parentEntity.ID);
+        if (cached)
+            return cached;
+        const md = this.ProviderToUse;
+        const relationships = [];
+        for (const rel of parentEntity.RelatedEntities) {
+            // Only walk One-To-Many (parent has many children)
+            if (rel.Type.trim() !== 'One To Many')
+                continue;
+            const childEntity = md.EntityByID(rel.RelatedEntityID);
+            if (!childEntity)
+                continue;
+            if (options.RequireTrackRecordChanges && !childEntity.TrackRecordChanges)
+                continue;
+            const parentKeyField = this.resolveParentKeyFieldFromRelationship(rel, parentEntity);
+            let collectionName;
+            let isCollection = false;
+            if (rel.RelatedRecordCollection) {
+                isCollection = true;
+                try {
+                    const parsed = typeof rel.RelatedRecordCollection === 'string'
+                        ? JSON.parse(rel.RelatedRecordCollection)
+                        : rel.RelatedRecordCollection;
+                    if (parsed && typeof parsed['Name'] === 'string') {
+                        collectionName = parsed['Name'];
+                    }
+                }
+                catch {
+                    // Ignore parse error; keep isCollection = true
+                }
+            }
+            relationships.push({
+                ChildEntityInfo: childEntity,
+                ChildJoinField: rel.RelatedEntityJoinField,
+                ParentKeyField: parentKeyField,
+                RelationshipInfo: rel,
+                CollectionName: collectionName,
+                IsCollection: isCollection,
+            });
+        }
+        this.reverseRelCache.set(parentEntity.ID, relationships);
+        return relationships;
+    }
+    /**
+     * Discover forward FK references on an entity.
+     */
+    discoverForwardReferences(entity, options) {
+        const cached = this.forwardRefCache.get(entity.ID);
+        if (cached)
+            return cached;
+        const md = this.ProviderToUse;
+        const refs = [];
+        for (const field of entity.Fields) {
+            if (!field.RelatedEntityID)
+                continue;
+            if (this.isSystemFKField(field.Name))
+                continue;
+            const isSelf = UUIDsEqual(field.RelatedEntityID, entity.ID);
+            const targetEntity = isSelf ? entity : md.EntityByID(field.RelatedEntityID);
+            if (!targetEntity)
+                continue;
+            if (options.RequireTrackRecordChanges && !targetEntity.TrackRecordChanges)
+                continue;
+            const isHierarchy = field.IsHierarchy;
+            refs.push({
+                TargetEntityInfo: targetEntity,
+                FKFieldName: field.Name,
+                TargetKeyField: this.resolveParentKeyFieldFromFK(field, targetEntity),
+                IsSelf: isSelf,
+                IsHierarchy: isHierarchy,
+                IsEmbedded: false, // Embedded records are declared in subclasses or metadata
+            });
+        }
+        this.forwardRefCache.set(entity.ID, refs);
+        return refs;
+    }
+    // =========================================================================
+    // Data Loading
+    // =========================================================================
+    /**
+     * Load child records for a reverse relationship.
+     */
+    async loadChildRecords(parentNode, rel, options, contextUser, onFailure) {
+        const parentKeyValue = parentNode.RecordData[rel.ParentKeyField] ?? null;
+        if (parentKeyValue == null)
+            return [];
+        let extraFilter = `[${rel.ChildJoinField}] = '${EscapeSQLString(String(parentKeyValue))}'`;
+        if (!options.IncludeDeleted && this.entityHasSoftDelete(rel.ChildEntityInfo)) {
+            extraFilter += ` AND __mj_DeletedAt IS NULL`;
+        }
+        try {
+            const rv = RunView.FromMetadataProvider(this.ProviderToUse);
+            const result = await rv.RunView({
+                EntityName: rel.ChildEntityInfo.Name,
+                ExtraFilter: extraFilter,
+                ResultType: 'simple',
+            }, contextUser);
+            if (!result.Success) {
+                LogError(`DependencyGraphWalker: Failed to load children of ` +
+                    `${parentNode.EntityName} via ${rel.ChildEntityInfo.Name}.${rel.ChildJoinField}: ` +
+                    `${result.ErrorMessage}`);
+                onFailure(result.ErrorMessage || 'the query failed');
+                return [];
+            }
+            return result.Results;
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            LogError(`DependencyGraphWalker: Error loading child records: ${msg}`);
+            onFailure(msg);
+            return [];
+        }
+    }
+    /**
+     * Load a single record's data by primary key.
+     */
+    async loadRecordData(entityInfo, key, contextUser) {
+        const rv = RunView.FromMetadataProvider(this.ProviderToUse);
+        const result = await rv.RunView({
+            EntityName: entityInfo.Name,
+            ExtraFilter: key.ToWhereClause(),
+            ResultType: 'simple',
+        }, contextUser);
+        if (!result.Success || result.Results.length === 0) {
+            LogError(`DependencyGraphWalker: loadRecordData returned empty for entity ` +
+                `'${entityInfo.Name}' with key ${key.ToConcatenatedString()}`);
+            return {};
+        }
+        return result.Results[0];
+    }
+    // =========================================================================
+    // Node Registration
+    // =========================================================================
+    /**
+     * Build a DependencyNode from record data, register it in the visited set,
+     * and attach it as a child of the parent. Returns null if already visited.
+     */
+    registerNode(entityInfo, recordData, relationship, parentNode, visited, stats, discoveringEdge, isSubtypeRow) {
+        const key = BuildCompositeKeyFromRecord(entityInfo, recordData);
+        const vKey = this.visitKey(entityInfo.Name, key.ToConcatenatedString());
+        if (visited.has(vKey)) {
+            stats.VisitedSkips++;
+            return null;
+        }
+        visited.add(vKey);
+        const node = {
+            EntityName: entityInfo.Name,
+            EntityInfo: entityInfo,
+            RecordKey: key,
+            RecordID: key.ToConcatenatedString(),
+            RecordData: recordData,
+            Relationship: relationship,
+            Children: [],
+            Depth: parentNode.Depth + 1,
+            DiscoveringEdge: discoveringEdge ?? null,
+            IsSubtypeRow: isSubtypeRow ?? false,
+        };
+        parentNode.Children.push(node);
+        this.incrementEntityCount(stats, entityInfo.Name);
+        return node;
+    }
+    // =========================================================================
+    // Logging
+    // =========================================================================
+    /** Create an empty stats accumulator. */
+    createEmptyStats() {
+        return {
+            EntityCounts: new Map(),
+            TotalRecords: 0,
+            AncestorSkips: 0,
+            VisitedSkips: 0,
+            ForwardOnlySuppressions: 0,
+        };
+    }
+    /** Increment the per-entity record counter. */
+    incrementEntityCount(stats, entityName) {
+        stats.TotalRecords++;
+        stats.EntityCounts.set(entityName, (stats.EntityCounts.get(entityName) ?? 0) + 1);
+    }
+    /**
+     * Log a detailed summary of the walk.
+     */
+    logWalkSummary(rootEntityName, options, stats) {
+        const entityBreakdown = Array.from(stats.EntityCounts.entries())
+            .sort((a, b) => b[1] - a[1])
+            .map(([name, count]) => `    ${name}: ${count}`)
+            .join('\n');
+        LogStatus(`DependencyGraphWalker: Walk complete for '${rootEntityName}'\n` +
+            `  Total records: ${stats.TotalRecords}\n` +
+            `  Unique entities: ${stats.EntityCounts.size}\n` +
+            `  Ancestor skips: ${stats.AncestorSkips}\n` +
+            `  Visited skips: ${stats.VisitedSkips}\n` +
+            `  Forward-only suppressions: ${stats.ForwardOnlySuppressions}\n` +
+            `  Max depth: ${options.MaxDepth}\n` +
+            `  Per-entity breakdown:\n${entityBreakdown}`);
+    }
+    // =========================================================================
+    // Helpers
+    // =========================================================================
+    /** Build a unique key for the visited set: "EntityName::recordID" */
+    visitKey(entityName, recordId) {
+        return `${entityName}::${recordId}`;
+    }
+    /**
+     * Determine the parent key field from an EntityRelationship record.
+     */
+    resolveParentKeyFieldFromRelationship(rel, parentEntity) {
+        if (rel.EntityKeyField && rel.EntityKeyField.trim().length > 0) {
+            return rel.EntityKeyField;
+        }
+        return parentEntity.FirstPrimaryKey.Name; // first-pk-ok: FK target — relationship without explicit EntityKeyField joins on parent single key column
+    }
+    /**
+     * Determine the target key field from a FK field definition.
+     */
+    resolveParentKeyFieldFromFK(fkField, targetEntity) {
+        if (fkField.RelatedEntityFieldName && fkField.RelatedEntityFieldName.trim().length > 0) {
+            return fkField.RelatedEntityFieldName;
+        }
+        return targetEntity.FirstPrimaryKey.Name; // first-pk-ok: FK target — column without RelatedEntityFieldName references target single key column
+    }
+    /** Check if a field name matches a system/infrastructure FK pattern. */
+    isSystemFKField(fieldName) {
+        return SYSTEM_FK_SKIP_PATTERNS.some(pattern => pattern.test(fieldName));
+    }
+    /** Check if an entity should be skipped based on filter options. */
+    shouldSkipEntity(entityName, options) {
+        if (options.ExcludeEntities.length > 0 && options.ExcludeEntities.includes(entityName)) {
+            return true;
+        }
+        if (options.EntityFilter.length > 0 && !options.EntityFilter.includes(entityName)) {
+            return true;
+        }
+        return false;
+    }
+    /** Check if an entity has a soft delete field. */
+    entityHasSoftDelete(entityInfo) {
+        return entityInfo.Fields.some(f => f.Name === '__mj_DeletedAt');
+    }
+    /** Apply defaults to walk options. */
+    resolveDefaults(options) {
+        return {
+            MaxDepth: options.MaxDepth ?? 10,
+            EntityFilter: options.EntityFilter ?? [],
+            ExcludeEntities: options.ExcludeEntities ?? [],
+            IncludeDeleted: options.IncludeDeleted ?? false,
+            RequireTrackRecordChanges: options.RequireTrackRecordChanges ?? true,
+            IncludeSoftLinks: options.IncludeSoftLinks ?? false,
+            IncludeSubtypes: options.IncludeSubtypes ?? false,
+            FollowHierarchies: options.FollowHierarchies ?? false,
+            ListNonCuratedInbound: options.ListNonCuratedInbound ?? false,
+            EdgePolicy: options.EdgePolicy,
+            OnLoadFailure: options.OnLoadFailure,
+        };
+    }
+}
+//# sourceMappingURL=DependencyGraphWalker.js.map