What an Edge Knows: Provenance, Inference, and Trust
In Graphify, an edge is not merely a line drawn between two names. It is a claim about a relationship, tied to a relation type, source context, and confidence category. This chapter examines that evidence contract so a reader can tell the difference between a connection explicitly present in the source, one resolved from surrounding structure, and one that should remain an open question. That distinction is what makes the graph useful for navigation without turning a convenient path into an unsupported conclusion.
The previous chapter followed different inputs into a common graph. Convergence makes the contract more important, not less. A tree-sitter parser, a semantic extractor, and a deduplication pass may all contribute to the same topology, but they do not know things in the same way. The graph has to preserve enough provenance for a reader to ask not only “what is connected?” but also “what supports this connection, and what should I verify next?”
A node is a claim with a place
The smallest useful unit in Graphify is not an anonymous token. A node has an identity and a human-readable label, but it also has a source file and, when available, a source location. Those fields anchor the node in the material from which it was extracted. A function node is not just the word “handle”; it is a particular entity associated with a particular location. A document or concept node can carry a different file type and source context, but the same principle applies: the reader needs a way to move from the graph's representation back to the material behind it.
An edge adds a second layer of specificity. It names two endpoints and describes the relationship between them. imports, calls, inherits, references, and semantic similarity do not mean the same thing, so the relation type is part of the evidence rather than a decorative label. An import link can guide the reader to a dependency boundary. A call link suggests a direction of execution or at least a recorded invocation relationship. A reference link may point to a document or rationale. A semantic-similarity link says that the extraction process found a conceptual connection, not that one entity invokes the other.
Source location matters at the edge as well as at the node. The location of a function definition answers “where is this thing declared?” The location attached to a relation can answer “where was this call, import, or reference observed?” Keeping those questions separate prevents a graph from pointing the reader to a definition line when the interesting evidence is the use site. It also helps explain why an edge exists when several symbols have similar names.
Graphify's persisted representation can carry more than ordinary pairwise links. Hyperedges represent group relationships that connect several nodes at once. That matters when a semantic extraction describes a group of concepts or when a relationship cannot be faithfully reduced to a sequence of two-node links. The larger lesson is not that every reader needs to inspect hyperedge storage. It is that the graph's data model is designed to preserve relationships as structured evidence rather than flattening everything into a similarity ranking.
This structure creates a useful discipline for reading results. Consider a query that returns a service, a validator, and a document. The node labels tell the reader what the objects are called. Their source files and locations say where to inspect them. The edge relations say whether the connection is an import, call, reference, or conceptual link. Without those layers, the result may look coherent while leaving the reader unable to distinguish an architectural relationship from two names that happen to occur near one another.
The same discipline applies to identity. A mixed extraction pipeline may describe one file through a structural pass and a semantic pass. If those descriptions receive different identifiers and are not reconciled, the graph can split one source entity into two disconnected nodes. If two unrelated entities share a label and are merged by name alone, the graph can create a false unity. Graphify's build and deduplication logic therefore has to balance two risks: ghost duplicates that hide continuity, and over-merges that erase real boundaries. Provenance—especially source file and file type—helps make that balance possible.
A useful reading test is to ask three questions of any returned relationship. First, what are the endpoints in the source: definitions, uses, files, or concepts? Second, what kind of relation is being asserted between them? Third, where was that relation observed or resolved? If the answer names only two labels, the graph has not supplied enough context for a careful judgment. If it includes a relation and location but no confidence, the reader still cannot tell whether the connection was written directly or reconstructed. The evidence contract is valuable because it makes these questions answerable without forcing the reader to reverse-engineer the extractor.
This also explains why a source file is not a complete explanation. A file path establishes where a node or edge was found; it does not establish why the code was designed that way, whether a branch is reachable, or whether a document's interpretation remains current. The graph keeps the location close enough to the relationship that the reader can inspect those questions efficiently. It does not claim that metadata can stand in for the source's full meaning.
The diagram captures a simple but consequential idea: the graph is not self-grounding. Nodes and edges come from source evidence; locations let the reader return to that evidence; confidence describes how the relationship was established; and verification remains an available next step. The graph is useful because it makes this chain compact and navigable, not because it eliminates the chain.
Confidence is a workflow, not a decoration
Graphify uses three principal confidence categories. EXTRACTED means that a relationship is stated directly in the source. An import statement, a written call, or an explicit inheritance declaration can support this kind of edge. The category does not mean that the entire system behavior has been proven; it means the particular relationship was found as an explicit source fact.
INFERRED means that the relationship was resolved or deduced from available evidence. A cross-file call can be inferred when a call site and a definition align through names, types, scope, or other structural context. A semantic extractor can infer that a code concept and a document concept are related even when neither source contains a literal reference to the other. Inferred edges may carry a confidence score, but the score remains a calibrated description of the extraction evidence. It is not a measurement of runtime probability, business importance, or truth in every context.
AMBIGUOUS means that the system cannot safely choose among possibilities or regards the relationship as uncertain. Keeping that edge can be more useful than deleting it. Deletion would make the graph appear cleaner while hiding a question the reader may need to answer. An ambiguous connection can become a review queue: inspect the competing definitions, clarify the source, or decide whether the relationship matters to the current task. In this sense, uncertainty is not a failure of the graph's user interface. It is information about where the graph's automatic reconstruction stops being decisive.
The categories also change how a reader should act. An extracted import is a reasonable basis for following a dependency immediately. An inferred call is a lead: it can focus source inspection, but the reader should confirm the definition and the call site when the distinction matters. An ambiguous link should not be used as if it settled the question; it tells the reader to investigate the relationship or narrow the query. The same graph can therefore support fast orientation and careful verification, provided the confidence label survives into the result.
Graphify exposes that distinction in its report and navigation surfaces. A report can show the proportions of extracted, inferred, and ambiguous edges, including an average confidence measure for inferred relationships. Node and neighbor views can display relation and confidence tags. Path output can preserve the relation on each hop. These are small presentation decisions with a large effect: they let the reader see whether a seemingly authoritative answer rests mostly on source-explicit structure or on a chain of reconstruction.
Confidence also affects what the analysis layer chooses to highlight. A surprising-connection score can treat an ambiguous or inferred link as noteworthy because uncertainty makes it worth review. But not every inferred link deserves the same attention. The repository's analysis logic suppresses some inferred calls or uses relationships that cross language boundaries or connect code to documentation, because label matching in those settings can create plausible resolver pollution. At the same time, it preserves explicit links and treats semantic-similarity relationships as meaningful cross-boundary signals rather than automatically discarding them.
That asymmetry is important. A simple rule such as “all inferred links are bad” would throw away the very relationships that make a mixed graph useful. A rule such as “all inferred links are useful” would reward false positives merely because they create more topology. Graphify instead uses relation, file type, language boundary, confidence category, and semantic context together. The result is not perfect certainty; it is a more disciplined prioritization of what deserves attention.
The conservative filters are also a form of interface design. They keep the graph from presenting a resolver's most fragile guesses as its most interesting discoveries. At the same time, they leave room for an explicit or semantically meaningful cross-boundary link to survive, because a relationship between code and a paper may be precisely what a mixed corpus is meant to reveal. The system is not choosing between “structure” and “meaning” once and for all. It is deciding which kinds of evidence deserve which kind of prominence.
A confidence audit gives the reader a way to inspect that balance at graph scale. If most edges are extracted, the graph may be structurally grounded but still narrow in what it can represent. If many are inferred, the graph may be richer but require more review. A high share of ambiguous edges can indicate unresolved naming or scope problems, or simply a corpus whose relationships are genuinely difficult to determine. None of these distributions is automatically good or bad; their significance depends on the task and the source mix. What matters is that the report exposes the distribution instead of presenting one undifferentiated relevance score.
The distinction between an observation and an interpretation should remain visible even when a graph-wide analysis gives the link a memorable name. A “god node” is a high-connectivity result, not a declaration that the project considers the entity conceptually central. A “surprising connection” is a ranked investigative lead, not proof that the connection was previously unknown or architecturally intentional. A community is a connectivity grouping, not necessarily a team boundary or a formal subsystem. Confidence and provenance stop these analytical labels from becoming stronger than the evidence beneath them.
This is why an ambiguity-aware graph can be more honest than a clean-looking search result. A ranked text match usually says how well a fragment resembles the query. It does not necessarily tell the reader whether the fragment defines the symbol, describes it, or merely mentions it. Graphify's evidence labels do not solve that problem by themselves, but they make the question explicit and attach it to an inspectable relationship.
What confidence does not tell you
A confidence category cannot prove runtime behavior. An extracted call can be unreachable, guarded by a condition, or obsolete in the current deployment. An inferred relationship can be reasonable and still resolve to the wrong same-named entity. An ambiguous edge can conceal a relationship that matters, but it can also be noise. The labels describe how the graph was built; they do not replace tests, execution traces, design decisions, or a reader's knowledge of the domain.
Nor do they prove that the graph is current. A source location can be precise while the graph is stale. A cached semantic result can retain an old interpretation after a document changes. A clean confidence audit can describe an incomplete corpus if discovery excluded a file or an extractor failed. Provenance has to be read alongside freshness and scope. “This link was explicitly extracted” is not the same statement as “this link is still valid today.”
The labels also do not supply a complete false-positive or false-negative rate. The repository documents conservative filters for some likely pollution and tests those distinctions, but it does not establish that every language, document type, dynamic construct, or semantic backend has the same quality. A reader should treat confidence as a decision aid: it tells them what kind of verification is appropriate, not whether verification is unnecessary.
In practice, verification can be proportional rather than absolute. A reader orienting themselves in an unfamiliar repository may follow an inferred edge to discover the right neighborhood. A reader reviewing a security boundary or changing a high-consequence behavior should inspect the source locations and competing candidates before relying on it. An ambiguous edge can be useful in both cases, but the first reader treats it as a lead while the second treats it as an unresolved condition. The confidence label makes that difference explicit without dictating one workflow for every question.
That is the practical meaning of trust in Graphify. Trust is not a single score attached to the whole graph. It is a chain from source evidence to node identity, from node identity to relation type, from relation type to confidence, and from confidence to an action such as follow, narrow, compare, or verify. Once that chain is visible, the next problem becomes manageable: how should Graphify select a bounded set of nodes and edges for a question without burying the reader in the rest of the graph?