Why Software Should Be a Graph, Not Text

Gábor Heizer — Wed, 03 Jun 2026 20:51:54 +0000

Software is still usually treated as text. We write source files, patch lines, review diffs, and ask tools to infer meaning from syntax. That model works because humans are good at reading convention, context, and intent. It is much less natural for AI systems. A model can produce convincing text while still losing the structure that makes a program correct: types, data flow, control flow, ownership, dependencies, and the relationship between a requested change and the behavior that should be preserved.

DUUMBI starts from a different premise: program meaning should be represented as a typed semantic graph first, with text as a secondary interface. In DUUMBI, program logic lives in JSON-LD graph data. Nodes represent program structure. Edges represent relationships. Stable identifiers let humans and agents point to specific parts of the program without relying on line numbers. The compiler then parses the graph, builds a semantic graph IR, validates it, lowers it through Cranelift, links it with a runtime, and produces a native binary.

That is the core thesis: if software is edited by both humans and AI agents, the durable source of truth should be the program's structure, not just the text that spells it.

Why Text Is A Weak Substrate For AI Coding

Text is a powerful human interface, but it is a lossy representation for machine reasoning. A source file mixes many layers at once: syntax, semantics, formatting, naming conventions, local style, module boundaries, and incidental ordering. Humans learn to separate those layers. AI coding tools often have to reconstruct them from fragments of files, prompts, test failures, and diffs.

That creates a familiar failure mode. A tool can make a patch that looks plausible in the diff, compiles in one path, and still violates a hidden invariant elsewhere. The problem is not that text is bad. The problem is that text is an indirect carrier for program meaning. A line-based patch does not explicitly say which semantic node changed, which edges must remain valid, or which behavior the change is meant to preserve.

For human-only programming, this indirection is manageable. For agentic programming, it becomes expensive. Every edit requires the agent to recover structure from the text, mutate it, and then rely on downstream tools to tell it whether the semantic shape survived. The feedback loop is late and noisy. Syntax, type, graph, and behavior problems all arrive as separate after-the-fact signals.

DUUMBI treats that as an architectural problem. Instead of asking agents to guess the structure from text, it provides them a structured representation to inspect and mutate.

What Changes When Program Meaning Is A Graph

A graph representation makes relationships first-class. A function can have a stable identity. A block can point to its operations. An operation can point to its operands. A type can be attached to the node that needs it. Metadata can record where a node came from, what it means, or how it should be reviewed.

This matters because software correctness is mostly relational. The question is rarely, "Did this line change?" The better question is, "Did this change preserve the intended relationship between intent, graph structure, types, generated code, runtime behavior, and evidence?" A semantic graph provides the toolchain a place to represent those relationships directly.

In DUUMBI, the graph is not just documentation. It is the compiler input. The README describes the pipeline plainly:

.jsonld -> Parser -> Semantic Graph -> Validator -> Cranelift -> binary

The architecture reference expands that pipeline: JSON-LD files are parsed into typed AST structures, converted into a semantic graph backed by petgraph, run through validation, lowered into Cranelift IR, linked with a C runtime, and emitted as a native binary. The graph is therefore not an annotation around a normal text program. It is the program representation the compiler consumes.

How DUUMBI Represents Program Logic

DUUMBI stores program logic as JSON-LD. JSON-LD is important because it gives graph data a web-native identity model: nodes can have stable identifiers, namespaced types, and explicit relationships. In the current compiler, those graph files are parsed into typed structures, then assembled into a semantic graph using StableGraph. That choice is practical. Stable graph indices are useful when a tool needs to mutate or inspect a program without invalidating every reference after a local change.

The repository architecture documents node identifiers such as duumbi:main/main/entry/2. That kind of identifier is more useful to an agent than "line 47" because it names a program location by role. A compiler, review tool, or AI agent can refer to the same semantic object even if a presentation layer later changes.

DUUMBI's type and operation set has grown beyond a toy arithmetic example. The architecture reference lists integer, float, boolean, string, array, struct, borrow, result, and option-oriented operations. The compiler boundary is also explicit: Cranelift details stay inside the compiler module behind a backend interface, while the rest of the system works in terms of DUUMBI's graph and type concepts.

The important point is not that every future language feature is finished. The important point is that DUUMBI's durable abstraction is already graph-shaped. That provides both humans and agents a more inspectable target than raw source text.

Validation Before Compilation

If AI is allowed to mutate software, validation has to move closer to the edit. DUUMBI's graph pipeline makes validation a central step rather than an afterthought. A graph mutation is only useful if the graph still parses, still builds, still validates, and still compiles for the claim being made.

The architecture reference calls this a semantic fixed point: a graph is compilable only when it passes schema validation, type checking, and relevant tests. That is a strong design direction, but it should not be oversold. It does not mean arbitrary natural language becomes correct software. It means the system has a structural place to reject invalid mutations before they become trusted product behavior.

This is the distinction DUUMBI is trying to make. AI-generated patches should not be accepted because the text looks reasonable. They should be accepted only after the graph, compiler, tests, and review evidence agree.

Where AI Agents Fit

DUUMBI's agent model is designed around bounded graph mutation. The architecture reference describes an AI mutation pipeline that takes a user request and turns it into a set of patch operations, which are then applied to JSON-LD, and the patched value is parsed, built, and validated before being written. There is also an undo history, so the graph state can be restored.

The repository also separates read-only Query behavior from write-capable Agent or Intent flows. That separation is important. A user should be able to ask "what exists?" or "where does this behavior live?" without accidentally asking a tool to mutate the workspace. When mutation is needed, it should be explicit, bounded, and verified.

Intent-driven development extends that idea. DUUMBI can represent a requested change as an intent spec with acceptance criteria, modules, and test cases, and then coordinate work against that spec. The current E2E scoring documentation measures generated intents across JSON validity, module structure, test coverage, edge cases, and acceptance criteria. That is not a production guarantee, but it shows the direction: evaluate agent work against structured criteria, not vibes.

What DUUMBI Can Claim Today

DUUMBI can currently claim the architecture and implementation shape documented in its public repository: JSON-LD graph input, semantic graph construction, validation, Cranelift lowering, linking to native binaries, read-only Query mode, bounded graph mutation, and Intent workflow concepts. The README links the public website, docs, and repository. At publication time, those public links should be checked again, because a marketing article should not send readers to dead surfaces.

The project can also claim that it is designed for evidence-oriented agentic development. The source tree contains parser, graph, compiler, agents, intent, query, telemetry, benchmark, registry, and Studio-related areas. Tests and E2E docs provide evidence to candidates when the article discusses specific behavior. Those claims should remain narrow. A unit test for a showcase parser does not prove a complete public demo. A local architecture document does not prove a production customer workflow. The article should be careful about that boundary.

What DUUMBI should avoid claiming as current fact is just as important. It should not promise that arbitrary natural language always becomes correct software. It should not claim production self-healing, silent updates, autonomous repair acceptance, or customer telemetry as present behavior unless separate public evidence proves those claims. It should not treat stale issue references as proof that showcases are complete. The credible story is already strong enough: DUUMBI is building a compiler and development workflow where program meaning is structured first.

Why This Matters

AI coding has made software feel more fluid, but fluidity alone is not reliability. The easier it becomes to generate code, the more important it becomes to know what changed, why it changed, what structure it affected, and which evidence supports accepting it.

The same issue appears in ordinary code review. A pull request can show a small textual diff while hiding a large semantic consequence. A renamed function might be harmless, or it might break a contract with a generated artifact. A new branch might be local control flow, or it might change the assumptions behind a whole execution path. Reviewers use tests, types, conventions, and experience to recover that meaning. A graph-centered system tries to make more of that meaning explicit before review begins.

That does not remove the need for judgment. DUUMBI still needs tests, human review, source-backed claims, and careful release boundaries. The advantage is that each of those checks can point at structure. A reviewer can ask which graph nodes changed. A validator can reject malformed relationships. An intent system can compare requested behavior with acceptance criteria. A future documentation or telemetry layer can attach evidence to the semantic object it describes instead of burying it in prose or logs.

This distinction is also why the graph thesis is different from a generic "AI writes code" pitch. The goal is not to make agents sound more confident. The goal is to provide agents fewer opportunities to be confidently wrong. A system that exposes program structure provides the agent a smaller, more precise surface to inspect and mutate. A system that validates every mutation gives humans a better starting point for review. A system that records evidence gives later reviewers a way to understand why a change was accepted.

Text files are not going away. Humans still need readable explanations, documentation, examples, and escape hatches. But if the source of truth remains only text, agents will keep spending much of their effort reconstructing the structure that the system could have represented directly.

A semantic graph provides the toolchain a better substrate. It lets compilers, agents, validators, review tools, and humans talk about the same objects. It makes program relationships explicit. It creates a place for evidence to attach to structure. It also makes it easier to draw a clear line between exploration and mutation, between current behavior and future vision, and between a proposed change and an accepted one.

That is why DUUMBI argues software should be a graph, not text. Not because text is useless, and not because graphs magically solve correctness. The argument is more practical: AI-first software development needs a representation that can be inspected, validated, patched, compiled, and reviewed as a structure. DUUMBI is one attempt to make that representation the center of the toolchain.

Readers can explore the project at https://www.duumbi.dev/, read the docs at https://docs.duumbi.dev/, and inspect the source at https://github.com/hgahub/duumbi.

DEV Community: Gábor Heizer