How Egonex-AI's Knowledge Graph Validation Works and How to Debug Validation Failures

Egonex-AI validates every knowledge graph through a five-stage pipeline in packages/core/src/schema.ts that sanitizes input, normalizes aliases, auto-fixes recoverable errors, and performs fatal schema checks, returning detailed diagnostic issues for every correction or drop.

The Understand-Anything repository by Egonex-AI implements a robust validation system for knowledge graphs persisted to .understand-anything/knowledge-graph.json. Understanding this validation pipeline is essential for debugging why a graph fails to load or why specific nodes and edges disappear during processing.

The Five-Stage Validation Pipeline

The validation process is deliberately layered to transform malformed input into a clean, well-typed graph while reporting every problem encountered. Each stage is defined in packages/core/src/schema.ts and executed sequentially.

Stage 1: Sanitisation with sanitizeGraph

The first stage normalizes trivial inconsistencies that could break downstream processing.

• Null coalescing: Converts null values to empty arrays
• Enum normalization: Lower-cases enum-like strings to ensure consistency
• Optional field cleanup: Strips null from optional fields

This logic resides at lines 48-71 in packages/core/src/schema.ts. The function prepares raw data for stricter schema validation without modifying semantic content.

Stage 2: Alias Normalisation with normalizeGraph

LLM extractors often emit human-friendly aliases rather than canonical enum values. This stage resolves aliases using lookup tables defined in the source code.

• "func" → "function"
• "extends" → "inherits"
• "up" → "forward" (for edge direction)

The alias resolution logic is implemented at lines 68-94 in packages/core/src/schema.ts. Using NODE_TYPE_ALIASES, EDGE_TYPE_ALIASES, and DIRECTION_ALIASES, the system maps extractor output to schema-compliant values before validation.

Stage 3: Auto-Fix with autoFixGraph

Before rejecting malformed data, the system attempts automatic recovery. The autoFixGraph function supplies missing required fields with sensible defaults and coerces incorrect types.

Node defaults (lines 96-150):

• type: "file" for nodes missing type information
• complexity: "medium" for unlabeled complexity

Edge defaults (lines 166-210):

• direction: "forward" for edges without direction
• weight: 1 for unweighted edges (coercing strings to numbers)

Every auto-correction creates an entry in the issues array with level: "auto-corrected" and includes the path to the modified element.

Stage 4: Fatal Schema Checks with validateGraph

The validateGraph function performs unrecoverable validation using Zod schemas. If any fatal check fails, the function returns { success: false, fatal: "<message>" } instead of throwing.

Fatal validation tiers:

Tier	Check	Failure Condition	Result
4	Input type validation	Input is not an object or is null	Fatal: "Invalid input: not an object" (lines 100-104)
4	Collection integrity	nodes, edges, or other top-level arrays are not arrays	Invalid collection issue (lines 118-124)
4	Project metadata	Missing project.name or project.languages	Fatal: "Missing or invalid project metadata" (lines 132-140)
4	Node existence	No valid nodes remain after validation	Fatal: "No valid nodes found" (lines 158-164)
3	Node schema (Zod)	Node fails GraphNodeSchema validation	Node dropped with level: "dropped" issue (lines 144-154)
3	Edge integrity	Edge fails GraphEdgeSchema or references non-existent node IDs	Edge dropped with missing source/target issue (lines 170-202)
3	Layer/Tour validation	Layer or tour step schema mismatches	Dropped with path-specific issues (lines 210-240)

Zod Schema Definitions:

• GraphNodeSchema: lines 68-86
• GraphEdgeSchema: lines 88-95
• ProjectMetaSchema, LayerSchema, TourStepSchema: lines 92-110

When successful, validateGraph returns { success: true, data: <cleanGraph>, issues: [...] }.

Stage 5: Persistence Integration with loadGraph and saveGraph

The validation pipeline integrates with file operations in packages/core/src/persistence/index.ts.

Loading (loadGraph):

• Reads .understand-anything/knowledge-graph.json
• Unless options?.validate === false, invokes validateGraph
• Throws an Error containing the fatal message on validation failure (lines 94-100)

Saving (saveGraph):

• Writes sanitized graphs using sanitiseFilePaths to prevent absolute path leakage (lines 38-65)
• Ensures persisted data meets schema requirements before writing

How to Debug Validation Failures

When a knowledge graph fails validation, the system provides multiple diagnostic layers to identify the root cause.

Catch Fatal Errors During Loading

Wrap loadGraph calls in try/catch blocks to capture fatal validation errors. The error message includes the specific reason from the validateGraph fatal check.

import { loadGraph } from "@understand-anything/core/persistence";

try {
  const graph = loadGraph("/path/to/project");
  console.log(`Loaded ${graph.nodes.length} nodes`);
} catch (error) {
  console.error("Fatal validation error:", error.message);
  // Output: "Fatal validation error: Missing or invalid project metadata"
}

Inspect the Issues Array for Detailed Diagnostics

For non-fatal problems (dropped nodes, auto-corrected fields), inspect the issues array by calling validateGraph directly or loading with validate: false followed by manual validation.

import { validateGraph } from "@understand-anything/core/schema";
import { readFileSync } from "fs";

const raw = JSON.parse(readFileSync("knowledge-graph.json", "utf-8"));
const result = validateGraph(raw);

if (!result.success) {
  console.error("Fatal:", result.fatal);
  process.exit(1);
}

// View all auto-corrections and drops
console.table(result.issues);
// Columns: level, path, message, originalValue

Each issue object contains:

• level: "auto-corrected" or "dropped"
• path: JSON path to the offending element (e.g., nodes[5].type)
• message: Human-readable explanation
• originalValue: The pre-fix value that caused the issue

Common Validation Failures and Fixes

Missing Project Metadata Ensure the top-level project object includes name and languages arrays before validation.

Orphaned Edge References Edges referencing non-existent source or target node IDs are automatically dropped. Verify that all node.id values referenced in edges exist in the nodes array.

Invalid Enum Values Check that type, complexity, and direction fields use canonical values, not aliases. Refer to the alias tables in schema.ts if preprocessing LLM output.

Working with Validation Programmatically

Loading with Default Validation

import { loadGraph } from "./packages/core/src/persistence/index.js";

try {
  const graph = loadGraph("/path/to/project");
  console.log("✅ Graph validated:", graph.nodes.length, "nodes");
} catch (err) {
  console.error("🚨 Validation failed:", err.message);
}

Manual Validation for Debugging

import { validateGraph } from "./packages/core/src/schema.js";

const result = validateGraph(rawData);
if (!result.success) {
  console.error("Fatal blocker:", result.fatal);
} else {
  console.log("Auto-fixed issues:", result.issues.filter(i => i.level === "auto-corrected").length);
  console.log("Dropped elements:", result.issues.filter(i => i.level === "dropped").length);
}

Skipping Validation for Known-Good Data

import { loadGraph } from "./packages/core/src/persistence/index.js";

// Use when data is already validated or for performance
const graph = loadGraph("/path/to/project", { validate: false });
console.log("Loaded without validation:", graph.nodes.length);

Summary

• Egonex-AI's knowledge graph validation operates through a five-stage pipeline in packages/core/src/schema.ts: sanitisation, alias normalisation, auto-fix, fatal checks, and persistence integration.
• Sanitisation handles null values and case normalization, while alias normalisation maps LLM-friendly terms to canonical enums like "function" and "inherits".
• Auto-fix supplies missing defaults (e.g., type: "file", direction: "forward") and logs every correction in the issues array with level: "auto-corrected".
• Fatal checks use Zod schemas (GraphNodeSchema, GraphEdgeSchema) to reject malformed input, missing project metadata, or dangling edge references, returning detailed fatal messages.
• Debugging involves catching loadGraph errors for fatal issues and inspecting the issues array for dropped nodes or auto-corrections, using the path field to locate specific problems in the JSON structure.

Frequently Asked Questions

How do I identify which specific node caused a validation failure?

Inspect the issues array returned by validateGraph. Each entry includes a path property (e.g., nodes[3].type) that pinpoints the exact location of the error. For fatal errors thrown by loadGraph, you must call validateGraph manually on the raw JSON to access the detailed issues list before the exception terminates execution.

Why are my edges disappearing when I load the knowledge graph?

Edges are dropped when they fail Zod validation or when their source or target properties reference node IDs that do not exist in the nodes array. Check the issues array for entries with level: "dropped" and message containing "missing source" or "missing target" to identify which edges reference non-existent nodes.

Can I disable automatic fixing and force strict validation?

While you cannot disable auto-fix specifically, you can detect when auto-corrections occur by checking the issues array for level: "auto-corrected" entries after validation. To prevent loading corrected data, validate the graph manually using validateGraph before calling loadGraph with validate: false, and reject any result containing auto-correction issues.

What Zod schemas define the knowledge graph structure?

The validation relies on GraphNodeSchema (lines 68-86), GraphEdgeSchema (lines 88-95), ProjectMetaSchema, LayerSchema, and TourStepSchema (lines 92-110) in packages/core/src/schema.ts. These schemas enforce type constraints, required fields, and enum values for all entities in the knowledge graph.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}