zerolang: Graph-First Language with ProgramGraph and Agent Edits

zerolang: A Graph-First Experimental Language for Safer Program Understanding

Introduction zerolang is an experimental graph-first programming language that reimagines how developers and automated agents interact with code. Rather than reading and editing raw text blocks alone, zerolang uses a compiler-derived ProgramGraph as the primary interface for inspection, reasoning, and edits. The source text (.0) remains the durable, reviewable artifact, while the graph captures semantic facts the compiler derives from that source. Agents—ranging from IDE tools to automated repair systems—navigate the graph to inspect nodes, types, effects, ownership, capabilities, module edges, and more, allowing precise, semantic edits rather than ambiguous patching of text ranges.

What zerolang Is Dealing With

• A source-of-truth text format that is intentionally human-readable and reviewable
• A compiler-produced, checked ProgramGraph that represents the program’s semantic structure
• An agent-friendly interface that exposes concrete facts: node IDs, graph hashes, types, effects, ownership facts, capabilities, helper use, and module relationships
• A graph-edit workflow where edits are checked and validated by the compiler before any source rewrite
• A design emphasis on safety, performance, and simplicity, with explicit caveats about current security posture

Design Goals zerolang is engineered around several core aims that shape both the language and the tooling:

• Token efficiency: keep the syntax concise and inspectable
• Low memory usage: minimize the memory footprint of the graph and associated tooling
• Fast startup: enable rapid iteration cycles for agents and developers
• Fast builds: streamline the path from source to graph to executable
• Low runtime latency: ensure the graph-driven pipeline does not impose heavy runtime costs
• Zero dependencies: reduce external drift by keeping the stack lean and self-contained

Safety status The project takes a candid stance on security: vulnerabilities should be expected. zerolang is experimental and not yet ready for production systems, sensitive data, or trusted infrastructure. It is intended to run in isolated, disposable environments where exploration and learning can occur without risk to critical systems.

Graph Agents vs. Text: The Lossiness of Text One of the central motivations for zerolang’s graph-first approach is the recognition that textual patches are inherently lossy for program understanding. A text patch requires guesswork about which references are related, whether a given range is stale, whether a call resolves to the intended function, and whether edits preserve ownership, fallibility, effects, imports, and constraints. The ProgramGraph is the compiler-owned structure that serves as a navigable map for agents. It is designed to be traversed in slices: start from a symbol or diagnostic, move to a call or capability, then reference the surrounding semantic facts. This focus keeps context gathering precise and relevant while preserving source code as the durable artifact humans review.

The graph also changes how edits are performed. A graph edit can target an exact node, such as node #610c78bf, and specify expectations about a graphHash and field values. The compiler validates the edit, lowers it, writes source if needed, formats, reparses, and checks the result in a single coherent path. Refactors can be expressed as semantic operations (e.g., renaming a function node or replacing a resolved callee) rather than string-based search-and-replace followed by separate cleanup work.

Source Text: Durable but Tangled The .0 source remains intentionally regular and readable. It is designed to behave like durable data: easy to index, compare, format, audit, and regenerate—yet still readable as normal code. A small example shows typed signatures, infix expressions, fallibility, and explicit capability passing:

zero fn answer() -> i32 { return 40 + 2 } pub fn main(world: World) -> Void raises { if answer() == 42 { check world.out.write("math works\n") } }

In this snippet:

• answer is a typed function returning an i32
• main accepts a World argument and may raise
• a conditional demonstrates interaction with a capability (world.out) to write output
• explicit text escaping and string literals illustrate the language’s treatment of runtime messages

What the ProgramGraph Is and How It Is Used ProgramGraph artifacts are not the primary files humans edit; they are the compiler-derived inspection data that agents use to reason about code. A graph dump can reveal the checked structure of a program, including modules, nodes, and edges. For example, the following graph excerpt illustrates how a simple program can be represented:

zero graph dump examples/hello.0

Example output:

zero-graph v1 origin source-text
module "hello" hash "graph:b8a019041020df03"
node #ea5ea1ca Function name:"main" type:"Void" public:true fallible:true
node #f9ce8b3e Param name:"world" type:"World"
node #421a4d4b MethodCall name:"write" type:"Void"
node #610c78bf Literal type:"String" value:"hello from zero\n"
edge #421a4d4b arg #610c78bf order:0
edge #ea5ea1ca body #6c48dda8

The graph exposes explicit handles such as node IDs, graph hashes, resolved types, effects, ownership facts, capability facts, helper use, and module edges. The hash provides a contextual check for staleness, while node IDs designate edit targets for the inspected graph. This separation between the textual source and the semantic graph allows agents to operate with confidence about the current program state, independent of textual drift or partial edits.

Checked Graph Edits: A New Editing Paradigm zerolang offers checked graph edits for canonical .0 sources. The tool zero graph patch applies edits to the graph with strict preconditions, and then rewrites the source only after validation. This approach collapses the traditional loop of edit, format, reparse, check, and fix into a compiler-driven operation that is safer and more predictable. Consider a patch that updates a literal value on a particular node:

zero graph patch examples/hello.0 \
  --expect-graph-hash graph:b8a019041020df03 \
  --op 'set node="#610c78bf" field="value" expect="hello from zero\n" value="hello graph\n"'

This operation targets a checked semantic node and its field. The graph hash guards against stale context, and the expect clause ensures the field value aligns with what the agent previously inspected. If the value has changed, the edit is rejected, prompting the agent to re-check the state before attempting another patch. This mechanism ensures that edits preserve semantics and ownership constraints while enabling precise, refactor-style changes performed as graph operations.

Agent Workflow Interfaces: Accessing the Compiler's Knowledge The compiler exposes a set of workflow interfaces through stable, structured command outputs. These interfaces enable agents to load, inspect, repair, and validate code without relying on fragile textual heuristics. The CLI commands yield machine-readable results (often JSON) that describe the current state of the program and its graph.

Key interfaces include:

• Load Version-Matched Rules: The compiler ships with skill text that matches the binary, enabling agents to align their capabilities with the exact language rules in use.
• Examples:
  • zero skills list
  • zero skills get language
  • zero skills get diagnostics
  • zero skills get stdlib
• Inspect Compiler Facts: The compiler reports facts in a stable format to ensure agents can rely on consistent data.
• Commands with --json produce structured outputs:
  • zero tokens --json examples/hello.0
  • zero parse --json examples/hello.0
  • zero check --json examples/hello.0
  • zero graph dump examples/hello.0
  • zero graph --json examples/systems-package
  • zero size --json examples/point.0
• Compiler-Native Contracts: A suite of commands encapsulates the inspection and repair paths, avoiding reliance on editor plugins or separate services:
• zero skills get language: Version-matched language rules
• zero check --json: Diagnostics with code, span, expected/actual, repair metadata, and toolchain facts
• zero parse --json: Stable parse summary with declarations, function signatures, and body node kinds
• zero graph --json: Modules, imports, public symbols, capabilities, effects, ownership facts, safety, helpers, and interface fingerprints
• zero graph dump: Deterministic text representation of the ProgramGraph
• zero graph patch: Checked graph edits with graph-hash preconditions
• zero fix --plan --json: Typed repair plans that describe proposed fixes without editing files
• zero size --json: Retained helpers, size reasons, policy, safety facts, backend facts, and artifact budget data
• Repair With Diagnostics: When a diagnostic fails, zerolang provides a stable, structured representation of the diagnostic and can convert it into typed fix plans. For example:
• zero check --json conformance/check/fail/unknown-name.0
• A diagnostic may include:
  • code: NAM003
  • message: unknown identifier 'message'
  • expected: visible local, parameter, function, or builtin
  • actual: no matching visible symbol
  • repair: { id: declare-missing-symbol }
• You can generate repair guidance with:
  • zero explain --json TYP009
  • zero fix --plan --json examples/agent-repair-demo/broken.0
• A demonstration run illustrates a scripted flow:
  • Run: pnpm run agent:demo
  • See: examples/agent-repair-demo/ for the broken fixture, suggested edit, fixed fixture, and explain-rerun flow
• Compatibility Policy: zerolang is experimental and intentionally unstable. The project favors a single, current syntax and a single formatted style over backward compatibility:
• zero fmt --check examples/hello.0
• zero check --json examples/hello.0

Quick Start and Practical Use Install and run a quick test to see zerolang in action:

• Install:
• curl -fsSL https://zerolang.ai/install.sh | bash
• export PATH="$HOME/.zero/bin:$PATH"
• zero --version
• Check a program:
• zero check examples/hello.0
• Run a tiny program:
• zero run examples/add.0
• Expected output: math works
• Basic workflows:
• zero check examples/hello.0
• zero run examples/add.0
• zero build --emit exe --target linux-musl-x64 examples/add.0 --out .zero/out/add
• zero graph --json examples/systems-package
• zero size --json examples/point.0
• zero skills get zero --full
• zero doctor --json

Design Implications and Developer Experience

• A calm separation of concerns: The source remains the durable artifact humans review, while the ProgramGraph captures the compiler’s semantic view for agents.
• Predictable, structured inspection: Agents navigate the graph using explicit IDs, hashes, types, and field values, reducing the risk of unintended edits.
• Safer refactoring: Graph edits enable semantic transformations (renaming, callee replacement) that would be error-prone with text-only patches.
• Diagnostics-and-repair loop: Built-in diagnostics, explain plans, and repair workflows provide a guided path from error to resolution without ad-hoc patching.
• Progressive safety posture: The project openly acknowledges that vulnerabilities and edge cases exist, encouraging isolation and disposable environments for experimentation.

Practical Examples and How It Feels to Work with zerolang

• Understanding a small program via the graph:
• By inspecting a node representing a function (e.g., a function named "main"), agents can query its type, visibility, and fallibility.
• Edges reveal how a function uses its arguments, which methods are invoked, and how literals are connected to calls.
• The graph provides a deterministic snapshot of the program’s structure, enabling repeatable reasoning across tools.
• Editing with semantic precision:
• A graph patch can target a specific node’s field, such as updating a literal’s value or changing a function’s callee.
• The patch is only applied if the graphHash and the expected value align with the current graph state, preventing drift.
• Diagnostics that translate into action:
• When a symbol is unknown, a diagnostic is produced with a repair identifier (e.g., declare-missing-symbol).
• Agents can generate a plan to fix the issue, then re-run checks to validate the fix, ensuring a safe and auditable repair path.

A Glimpse of the Open Practical Reality zerolang is designed as a living research platform rather than a polished production language. Its emphasis on graph-driven semantics and compiler-managed edits is ambitious, aiming to reduce the guesswork that currently plagues code navigation and automated refactoring. The approach acknowledges that text-based patches are inherently lossy and error-prone for semantic edits, while the ProgramGraph offers a precise semantic surface for agents to operate upon. The result is a workflow where humans retain ownership of the source but gain powerful, semantically aware tools for inspection, modification, and verification.

Limitations and Candid Caveats

• Safety posture is intentionally conservative: expect security vulnerabilities and use isolated environments while experimenting.
• The ecosystem is still stabilizing: there may be breaking changes as graph APIs evolve and the language semantics mature.
• Graph-based workflows require a mental model shift: developers and tools must adapt to navigating graphs, IDs, and graph hashes rather than solely reading and patching text.
• Tooling parity: While many inspection commands exist, the breadth and depth of available graph facts and repair pathways continue to grow and may vary across versions.

Future Directions and Aspirations

• Expanded graph facts: Additional ownership, capability, and effect data to support even richer agent reasoning.
• More ergonomic repair pipelines: Higher-level repair abstractions that minimize boilerplate for common refactor patterns.
• Cross-language integration: Interfaces to interoperate with other languages or tooling ecosystems while maintaining the graph-first discipline.
• Enhanced safety guarantees: More robust preconditions and validation strategies to catch regressions before source edits are written.

Conclusion zerolang offers a provocative and methodical approach to programming where a compiler-generated ProgramGraph becomes the primary instrument for understanding, reasoning, and safely editing code. By decoupling the durable source text from the semantic graph, the system provides a precise, auditable, and scalable framework for agents to operate within. The design goals—token efficiency, low memory use, fast startup and builds, low runtime latency, and zero dependencies—reflect a strong ambition to enable rapid, semantically aware iteration. Yet the Safety status remains a sober reminder: this is an experimental project best explored in isolated environments, with careful attention to the evolving graph APIs, the stability of the commands, and the ongoing refinement of the agent workflow. If you are curious about how systems could evolve toward greater semantic clarity and programmable safety, zerolang offers a compelling glimpse into a graph-driven future of software engineering.