Zerolang Documentation

The correctness of Zero implementations is governed by manifest.json.

• manifest.json: This is the active correctness corpus. Every entry listed here has been verified against its corresponding Rosetta Code task behavior and produces a deterministic success output.
• Draft files: Files with .0 or .graph extensions that are not listed in manifest.json are considered draft compiler fixtures or standard-library smoke material and do not count towards Rosetta correctness coverage.

The Zerolang repository contains various examples categorized by complexity and domain to help you learn the language:

• Small programs: Basic logic like hello.graph, add.graph, and fallibility.graph.
• Memory and ownership: Primitives and collections like memory-primitives.graph, allocator-collections.graph, and ownership-cleanup.graph.
• CLI and files: Filesystem and CLI interactions like cli-file.graph, file-copy.graph, and resource-cli/.
• Data and web: Networking and data formats like json-api-client.graph, crm-api/, and std-http-request.graph.
• Compiler and agent workflows: Advanced patterns like compile-time-v1.graph, agent-repair-demo/, and error-tour/.

Unlike traditional programming where agents write text and rely on subsequent build/format steps to find errors, Zerolang uses a graph-native loop. Agents query the graph to understand structure and submit checked graph patches. This allows the compiler to reject invalid semantic edits immediately, before the program is even re-parsed.

The Zerolang Agent Loop:

1. Query the graph: Use tools to inspect declarations, types, calls, and blocks.
2. Submit a checked patch: Apply a specific semantic change.
3. Immediate validation: The compiler validates the patch against shape rules (required edges, node kinds, etc.) immediately.
4. Task validation: Run only the specific validation required for the task.

The std.json module provides tools for JSON validation, parsing, shallow field lookup, cursor-based access to objects and arrays, and caller-buffer writing.

Key Characteristics:

• Allocation Behavior: Validation and streaming are allocation-free. Parsing requires an explicit allocator. Direct writers write into caller-provided buffers.
• Error Handling: Maybe helpers return null on failure. Validation diagnostics (offset, line, column) are allocation-free.
• Field Lookup: Lookup is intentionally shallow, reading top-level object fields and returning raw slices or typed scalar decodes. For duplicate keys, name-based lookup returns the first match, while ordinal cursors preserve source order.
• String Decoding: std.json.stringDecode writes UTF-8 for Unicode escapes and rejects malformed surrogate pairs.

Zerolang operates using two synchronized views of a program:

1. The Graph: The primary program database. AI agents interact with this directly by inspecting and patching structured facts.
2. The .0 Projection: A human-readable text representation of the graph. Humans use this for code review and rare manual edits.

When writing or reading Zero syntax, you are interacting with the projection syntax, which maps directly to the declarations, types, and edges stored in the graph.

The std.time module provides tools for duration arithmetic, RFC 3339 date/time validation and parsing, and target-gated monotonic or wall-clock helpers.

Key Characteristics:

• Allocation Behavior: No allocation.
• Target Support: Duration math is target-neutral. Clock reads (monotonic, wallSeconds) and sleep require a time-capable target.
• Error Behavior: Helpers are infallible. RFC 3339 validators return Bool, and the epoch parser returns a provided fallback value if the input is invalid.
• Ownership: No ownership transfer occurs.

Unlike traditional parse-first compilers (e.g., Rust, Go, Zig) that begin by parsing text files into ASTs, Zerolang uses a graph-first compile path. The primary input for the compiler is the zero.graph store rather than source text.

This architecture allows agents and developers to interact with the compiler using graph facts directly. Instead of a cycle of writing text and waiting for a parser to validate it, you can query the graph for node handles, symbol facts, calls, and references, and then submit semantic patches. This reduces redundant parsing and ensures edits are expressed in terms the compiler already understands.

The std.io module is used for performing byte-level I/O operations on storage owned by the caller. It is not an ambient process I/O layer (like stdin/stdout); instead, it provides tools for managing spans, sequential streams, and line-based reading/writing using explicit buffers.

Key Characteristics

• Allocation Behavior: Uses caller-provided buffers; performs no hidden heap allocations.
• Error Behavior: Exact reads/writes return Maybe.none or false if there is insufficient input or an overflow occurs.
• Ownership: Operations either borrow or write directly to caller-owned storage.

Use the std.str module for allocation-free byte-string helpers. These operations work over spans and caller-owned storage.

Key Characteristics:

• Allocation-free: Functions that create new byte sequences require caller-provided storage. Functions that return spans borrow from the input or the provided storage.
• Byte-oriented: Helpers operate on byte spans and ASCII delimiter rules (space, tab, line feed, and carriage return). They do not implement Unicode case mapping, grapheme segmentation, or locale-aware text rules.
• Safety: Functions like reverse, repeat, replace, copy, and concat return null (via Maybe) if the provided buffer is too small. The destination buffer must not overlap the input.

The standard workflow for package work involves querying the graph, applying patches, and running checks/tests. The default input for these commands is the current directory.

zero query
zero patch --op help
zero patch --op 'addMain'
zero check
zero test
zero run -- <args>