# The Mental Model — zerolang in One Map > The simplest useful model of zerolang: what it is, its five design invariants, the main flows from source to running binary, and what facts change your predictions about its behavior. Read this first to anchor every other page. - Repository: vercel-labs/zerolang - GitHub: https://github.com/vercel-labs/zerolang - Human wiki: https://grok-wiki.com/public/wiki/vercel-labs-zerolang-9ab46b2a38e0 - Complete Markdown: https://grok-wiki.com/public/wiki/vercel-labs-zerolang-9ab46b2a38e0/llms-full.txt ## Source Files - `README.md` - `AGENTS.md` - `package.json` - `bin/zero` - `skill-data/zero-agent.md` - `examples/add.0` ---
Relevant source files The following files were used as context for generating this wiki page: - [README.md](README.md) - [AGENTS.md](AGENTS.md) - [package.json](package.json) - [bin/zero](bin/zero) - [skill-data/zero-agent.md](skill-data/zero-agent.md) - [skill-data/zero-language.md](skill-data/zero-language.md) - [skill-data/zero-diagnostics.md](skill-data/zero-diagnostics.md) - [skill-data/zero-builds.md](skill-data/zero-builds.md) - [examples/add.0](examples/add.0) - [examples/hello.0](examples/hello.0) - [examples/fallibility.0](examples/fallibility.0) - [examples/agent-repair-demo/broken.0](examples/agent-repair-demo/broken.0) - [examples/agent-repair-demo/fixed.0](examples/agent-repair-demo/fixed.0) - [examples/systems-package/src/main.0](examples/systems-package/src/main.0) - [native/zero-c/src/main.c](native/zero-c/src/main.c) - [native/zero-c/src/checker.c](native/zero-c/src/checker.c) - [native/zero-c/src/target.c](native/zero-c/src/target.c) - [native/zero-c/src/ir.c](native/zero-c/src/ir.c) - [scripts/agent-repair-demo.mts](scripts/agent-repair-demo.mts)
# The Mental Model — zerolang in One Map zerolang is a pre-1 experiment in building a programming language whose primary user is an AI agent, not a human. Every design choice—the small regular syntax, the structured JSON tooling surface, the embedded skill docs, the explicit error propagation—exists to make a language that an agent can learn on the fly, inspect deterministically, and repair from structured feedback without needing contextual guessing. This page gives you the fastest accurate picture of what zerolang is, how its pieces connect, and which facts actually change how programs behave. Read it before anything else; every other page in this wiki adds detail to the model laid out here. --- ## What zerolang Is, In One Sentence zerolang is a compiled, statically-typed language with a single native-C compiler (`zero-c`), a capability-gated standard library, and a CLI designed to emit machine-readable JSON at every inspection boundary so that agents can check, repair, build, and explain programs without inference from prose. Sources: [README.md:3-6](), [AGENTS.md:3-8]() --- ## Five Design Invariants These are the load-bearing commitments. If you change any of them you change what the language is. | # | Invariant | What It Buys | |---|-----------|--------------| | 1 | **Agent-first learnability** — small, regular surface; one obvious way per pattern | An agent can cold-start from examples and `zero skills get zero-language` without pre-training | | 2 | **Deterministic tooling** — every diagnostic, graph fact, size report, and fix plan is emittable as structured JSON | Agents consume JSON, not parsed terminal output; round-trip is exact | | 3 | **Standard-library depth** — common capabilities live in coherent `std.*` APIs, not dependency stacks | Most programs never need a package search; `use std.codec`, `use std.time`, etc. cover the common surface | | 4 | **Explicit effects** — `World`, `std.fs`, `std.args`, `std.env` are passed explicitly; effects are capabilities, not ambient globals | Target-gating is mechanical; a non-host target cannot silently drop a capability call | | 5 | **Explicit fallibility** — `raises`, `check`, `raise`, `Maybe` replace hidden failures | Errors propagate visibly; an agent reading source code can trace every fallible path without running it | Sources: [README.md:11-17](), [skill-data/zero-agent.md:45-49](), [skill-data/zero-language.md:8-18](), [skill-data/zero-language.md:111-127]() --- ## Repository Layout ```text zerolang/ ├── native/zero-c/ # The compiler — C source, single binary │ └── src/ │ ├── main.c # CLI dispatch, command routing, JSON emission │ ├── lexer.c / row_syntax.c # Two-tier lexer (classic + row layout) │ ├── parser.c # AST construction │ ├── checker.c # Type checker, provenance/borrow analysis │ ├── type_core.c / unify.c # Type inference and unification │ ├── ir.c # IR/MIR construction + specialization │ ├── mir_verify.c # MIR-level invariant verification │ ├── specialize.c # Generic monomorphization │ ├── emit_elf64.c # ELF/x64 direct emitter │ ├── emit_elf_aarch64.c │ ├── emit_macho64.c # Mach-O/x64 │ ├── emit_coff.c # COFF/Windows │ └── target.c # Target manifest and capability gating ├── examples/ # Runnable .0 programs and packages ├── conformance/ # Language and CLI snapshot fixtures ├── skill-data/ # Markdown skills embedded in the binary ├── scripts/ # Validation, release, agent demo tools (TypeScript) ├── docs/ # Public documentation site ├── extensions/vscode/ # VS Code extension └── bin/zero # Thin shell wrapper → .zero/bin/zero (native) ``` Sources: [AGENTS.md:64-70](), [native/zero-c/src/main.c:1-60]() --- ## The Main Flow: Source to Running Binary ```mermaid sequenceDiagram participant User/Agent participant bin/zero participant zero-c (native) participant Checker participant IR/MIR participant DirectEmitter participant OS User/Agent->>bin/zero: zero run examples/add.0 bin/zero->>zero-c (native): exec .zero/bin/zero run examples/add.0 zero-c (native)->>Checker: parse → type-check → provenance Checker-->>zero-c (native): diagnostics (JSON or stderr) zero-c (native)->>IR/MIR: build IR, specialize generics, verify MIR IR/MIR->>DirectEmitter: select target emitter (ELF/Mach-O/COFF/…) DirectEmitter-->>zero-c (native): native object / binary bytes zero-c (native)->>OS: exec produced binary OS-->>User/Agent: stdout output ``` `bin/zero` is a thin shell wrapper (`set -euo pipefail; exec $root/.zero/bin/zero "$@"`). It adds no logic — it either finds the native binary or exits 127 with a build instruction. The native compiler is the only real actor. Sources: [bin/zero:1-13](), [native/zero-c/src/main.c:29-58](), [native/zero-c/src/ir.c:1-10]() --- ## The Agent Repair Loop The second major flow is not compilation; it is the **inspect-explain-fix cycle** that the tooling is specifically designed for. This is what "agent-first" means in practice. ```mermaid sequenceDiagram participant Agent participant zero-c Agent->>zero-c: zero check --json broken.0 zero-c-->>Agent: {ok:false, diagnostics:[{code:"TYP009", repair:{id:"make-binding-mutable"}}]} Agent->>zero-c: zero explain --json TYP009 zero-c-->>Agent: {code:"TYP009", repair:{id:"make-binding-mutable"}, ...} Agent->>zero-c: zero fix --plan --json broken.0 zero-c-->>Agent: {mode:"plan", appliesEdits:false, fixes:[{id:"make-binding-mutable"}]} Agent->>Agent: apply edit (let → let mut) Agent->>zero-c: zero check --json fixed.0 zero-c-->>Agent: {ok:true, diagnostics:[]} ``` Key facts: - `zero fix` is **plan-only** in this compiler; it reports candidate repairs but does not edit files. Edits are the agent's responsibility. - Every diagnostic carries a stable `code` (e.g., `TYP009`, `NAM003`), a `repair` hint, and a `fixSafety` label (`format-only`, `behavior-preserving`, `api-changing`, `requires-human-review`). - `zero explain ` is a first-class command, not docs-site lookup. Sources: [scripts/agent-repair-demo.mts:23-56](), [skill-data/zero-diagnostics.md:19-46](), [examples/agent-repair-demo/broken.0](), [examples/agent-repair-demo/fixed.0]() --- ## The Language Surface ### Minimal program ```zero // examples/hello.0 pub fun main(world: World) -> Void raises { check world.out.write("hello from zero\n") } ``` - `pub fun` exports a function. Only `main` is the entry point. - `World` is the capability handle for all I/O. It is a parameter, not a global. - `raises` marks a fallible function. An open `raises` accepts any error; `raises { InvalidInput }` restricts it. - `check` propagates failure upward. Omitting it on a fallible call is a type error. ### Key syntax forms | Form | Meaning | |------|---------| | `let x = ...` | immutable binding | | `let mut x = ...` | mutable binding | | `shape Point { x: i32, y: i32 }` | product type | | `enum Mode { fast, small }` | C-like enum | | `choice Result { ok: i32, err: String }` | tagged union | | `fun f(v: T) -> T` | generic function | | `ref` / `mutref` | read / write borrow | | `Span` / `MutSpan` | contiguous view | | `Maybe` | optional value | | `raise Err` | explicit error raise | | `check expr` | propagate fallible result | | `test "name" { expect(true) }` | inline test block | Sources: [skill-data/zero-language.md:12-160](), [examples/add.0](), [examples/fallibility.0]() ### Effects are explicit capabilities ```zero // examples/systems-package/src/main.0 pub fun main(world: World) -> Void raises { check world.out.write("systems package\n") } ``` `World` is passed explicitly. There is no implicit I/O. Standard library modules — `std.fs`, `std.args`, `std.env`, `std.time`, `std.codec`, `std.parse` — are imported with `use` and called directly. Sources: [examples/systems-package/src/main.0:7-17](), [skill-data/zero-agent.md:45-46]() --- ## Target and Capability Model zerolang targets are manifest-driven. Each target is a named record with `os`, `arch`, `abi`, `objectFormat`, `linker`, `libc`, and a `capabilities` array. ```text darwin-arm64 → Mach-O, cc linker, [memory, stdio, args, env, fs, time, rand, net, proc] linux-musl-x64 → ELF64, zig cc linker, musl, [memory, stdio, args, env, fs, time, rand] linux-musl-arm64 → ELF64, zig cc, musl, [memory, stdio, time, rand] ← no args/env/fs win32-x64.exe → COFF ``` The capability array is checked at **compile time** against the APIs your program uses. If you call `std.fs` on a target that lacks `fs`, the checker emits `TAR002` before any code is generated. This is the mechanical enforcement behind Invariant 4 (explicit effects). Use `zero targets` to list the full manifest. Use `zero check --target ` to validate before cross-building. Sources: [native/zero-c/src/target.c:9-87](), [skill-data/zero-builds.md:48-56](), [skill-data/zero-diagnostics.md:52-54]() --- ## Embedded Skills The native binary bundles documentation as embedded skills, accessible at runtime: ```sh zero skills list # names + descriptions zero skills get zero-language # full skill content zero skills get zero-diagnostics zero skills get zero-builds zero skills get zero-stdlib zero skills get zero-testing zero skills get zero-packages zero skills get zero-agent ``` Skills are compiled from `skill-data/*.md` into the binary (`embedded_skills.inc`). An agent that knows nothing about Zero can bootstrap its understanding by running `zero skills get zero-language` before writing a single line of source. This is a first-class design goal, not a convenience feature. Sources: [native/zero-c/src/main.c:202-341](), [skill-data/zero-agent.md:14-20]() --- ## What Changes Your Predictions These are the facts that bifurcate behavior. Get them wrong and your mental model will produce false predictions. | Fact | Effect | |------|--------| | **Target selection** | Determines available capabilities and emitter (ELF64/Mach-O/COFF). Using `std.fs` on `linux-musl-arm64` is a compile error, not a runtime error. | | **`raises` annotation** | Open `raises` propagates any error upward. Closed `raises { Err }` restricts the set and is checked by the type system. Calling a fallible function without `check` is a type error. | | **`let` vs `let mut`** | Mutability is a static property. Writing to an immutable binding produces `TYP009`. The repair is always `make-binding-mutable`. | | **`bin/zero` vs installed `zero`** | `bin/zero` shells out to `.zero/bin/zero` (the locally built binary). If `.zero/bin/zero` is absent, it exits 127. The installed `zero` on `PATH` is a different binary for end users. In the repository, always use `bin/zero`. | | **`zero fix` is plan-only** | The compiler proposes edits but does not apply them. Applying patches is the caller's responsibility. | | **`--json` flag** | Changes output from human-readable stderr/stdout to a structured JSON object on stdout. Agent tooling must use `--json`; the prose format is unstable. | | **Direct emitters vs legacy C backend** | The generated-C backend has been removed. `BLD003` is the diagnostic code for any reference to it. All compilation paths go through the native direct emitters. | Sources: [skill-data/zero-diagnostics.md:37-65](), [skill-data/zero-builds.md:31-32](), [bin/zero:6-12](), [AGENTS.md:52-59]() --- ## Validation Entry Points | Command | What it covers | |---------|----------------| | `pnpm run conformance` | Language and CLI snapshot fixtures (`conformance/run.mjs`) | | `pnpm run native:test` | Native compiler unit tests (`scripts/test-native.sh`) | | `pnpm run docs:test` | Documentation site tests | | `pnpm run command-contracts` | Snapshot contracts on CLI JSON output shapes | | `pnpm run agent:demo` | End-to-end agent repair loop (`scripts/agent-repair-demo.mts`) | | `bin/zero check --json ` | Focused type-check with structured output | | `bin/zero fix --plan --json ` | Generate repair plan without applying edits | Conformance and command-contract tests run inside a sandbox by default (via `@vercel/sandbox`). Pass `ZERO_NATIVE_TEST_ALLOW_LOCAL=1` to run against the locally built compiler. Sources: [README.md:59-71](), [AGENTS.md:44-61](), [package.json:13-51]() --- ## Summary zerolang is a single-binary native compiler whose architecture is organized around one idea: every boundary an agent touches should return structured facts, not prose. The compiler (`native/zero-c`) owns the full pipeline from parsing through direct binary emission. The language enforces explicit effects (`World`), explicit fallibility (`raises`/`check`), and explicit mutability (`let mut`) at the type level so that an agent reading source can predict behavior without running it. Target capability gating catches mismatches at compile time, not at runtime. Skills embedded in the binary let an agent learn the language from the language itself. The repair loop—`check → explain → fix → check`—is a designed circuit, not an afterthought. Sources: [README.md:11-17](), [AGENTS.md:16-24](), [skill-data/zero-agent.md:1-63]()