# zerolang Mental Model Wiki

> zerolang is an agent-first programming language and compiler toolchain designed so AI agents can learn it on the fly, receive structured (JSON) diagnostics, and repair programs with deterministic fix plans. This wiki maps the mental model a reader needs to predict the system's behavior, boundaries, and safe-change rules.

This is a Grok-Wiki source-grounded repository wiki. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown wiki](https://grok-wiki.com/public/wiki/vercel-labs-zerolang-9ab46b2a38e0/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/wiki/vercel-labs-zerolang-9ab46b2a38e0.md)
- [Human interactive wiki](https://grok-wiki.com/public/wiki/vercel-labs-zerolang-9ab46b2a38e0)
- [GitHub repository](https://github.com/vercel-labs/zerolang)

## Repository

- Repository: vercel-labs/zerolang

- Generated: 2026-05-21T23:19:14.680Z
- Updated: 2026-05-21T23:20:25.773Z
- Runtime: Claude Code
- Format: Mental Model
- Pages: 8

## Pages

- [The Mental Model — zerolang in One Map](https://grok-wiki.com/public/wiki/vercel-labs-zerolang-9ab46b2a38e0/pages/01-the-mental-model-zerolang-in-one-map.md): 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.
- [Language Invariants — Types, Effects, and Fallibility](https://grok-wiki.com/public/wiki/vercel-labs-zerolang-9ab46b2a38e0/pages/02-language-invariants-types-effects-and-fallibility.md): The core Zero language rules an agent must internalize to write correct .0 source: explicit capabilities via World, opt-in mutability with let mut, mandatory raises + check for fallibility, the Maybe<T> pattern, and why integer casts require as. These invariants are the checkpoints the compiler enforces before any code runs.
- [Compiler Pipeline — From .0 Source to Native Binary](https://grok-wiki.com/public/wiki/vercel-labs-zerolang-9ab46b2a38e0/pages/03-compiler-pipeline-from-.0-source-to-native-binary.md): How the native C compiler (native/zero-c) processes a .0 file: lexer → parser → checker → IR → MIR verifier → direct emitter (ELF64 / Mach-O / COFF). Key invariant: generatedCBytes must be zero for a direct-frontend build. The legacy C bridge path is removed and must not be reintroduced.
- [CLI Command Surface — check, run, build, graph, size, fix](https://grok-wiki.com/public/wiki/vercel-labs-zerolang-9ab46b2a38e0/pages/04-cli-command-surface-check-run-build-graph-size-fix.md): The full set of zero CLI commands, their JSON output contracts, and when to use each. Commands are the only stable agent-facing interface: always pass --json for machine consumption. Key distinction: zero fix --plan is read-only (reports repairs, never edits files). Covers provenance guardrails and the sandbox execution requirement for conformance and native tests.
- [Diagnostics & Fix Plans — Structured Error Triage](https://grok-wiki.com/public/wiki/vercel-labs-zerolang-9ab46b2a38e0/pages/05-diagnostics-fix-plans-structured-error-triage.md): How zerolang surfaces compiler errors as machine-readable JSON with stable codes (NAM003, TYP009, TAR002, …), source spans, fixSafety levels, and repair ids. The agent-repair loop: check --json → explain <code> → fix --plan --json → apply the narrowest safe patch. Covers all fixSafety categories and when requires-human-review must block automation.
- [Packages & Modules — zero.json, Imports, and Dependency Resolution](https://grok-wiki.com/public/wiki/vercel-labs-zerolang-9ab46b2a38e0/pages/06-packages-modules-zero.json-imports-and-dependency-resolution.md): How multi-file Zero projects are structured: the zero.json manifest schema (package, targets, dependencies), how use-imports resolve from src/ (including mod.0 fallback), local path dependencies requiring zero.json, and the deterministic lock written to .zero/package-locks/. Key failure modes: IMP001 (unknown import), PKG001 (missing manifest), IMP002/PKG002 (cycles).
- [Standard Library & Targets — Capabilities, Modules, and Cross-Build Boundaries](https://grok-wiki.com/public/wiki/vercel-labs-zerolang-9ab46b2a38e0/pages/07-standard-library-targets-capabilities-modules-and-cross-build-boundaries.md): The two-tier stdlib model: target-neutral modules (std.mem, std.codec, std.parse, std.json, std.io) available everywhere versus hosted-capability modules (std.fs, std.net, std.http, std.args, World.out) that are target-gated and rejected at compile time on non-host targets. How to inspect target facts before cross-building and choose the right build profile.
- [Safe-Change Map — Agent Repair Loop, Testing, and Invariants to Preserve](https://grok-wiki.com/public/wiki/vercel-labs-zerolang-9ab46b2a38e0/pages/08-safe-change-map-agent-repair-loop-testing-and-invariants-to-preserve.md): The closing synthesis: the complete agent edit loop (read → change → check --json → explain → fix --plan → patch → test), the conformance fixture contract (pass/ vs fail/), xfail test markers, the no-legacy-C invariant to guard in every build output, safe-change rules for the pre-1 unstable surface, and the sandbox requirement that keeps native test artifacts off developer machines by default.

## Source Files

- `AGENTS.md`
- `bin/zero`
- `conformance/check/pass`
- `conformance/diagnostics`
- `conformance/native`
- `conformance/packages`
- `conformance/provenance-surface.json`
- `conformance/run.mjs`
- `examples/add.0`
- `examples/branch.0`
- `examples/fallibility.0`
- `examples/generic-pair.0`
- `examples/memory-primitives.0`
- `examples/point.0`
- `examples/std-http-request.0`
- `examples/std-path-io.0`
- `examples/std-platform.0`
- `native/zero-c/src/call_resolve.c`
- `native/zero-c/src/checker.c`
- `native/zero-c/src/emit_elf64.c`
- `native/zero-c/src/ir.c`
- `native/zero-c/src/lexer.c`
- `native/zero-c/src/main.c`
- `native/zero-c/src/mir_verify.c`
- `native/zero-c/src/parser.c`
- `native/zero-c/src/specialize.c`
- `native/zero-c/src/target.c`
- `native/zero-c/targets`
- `package.json`
- `README.md`
- `scripts/agent-repair-demo.mts`
- `scripts/native-test-sandbox.mts`
- `scripts/provenance-guardrails.mts`
- `scripts/snapshot-command-contracts.mts`
- `skill-data/zero-agent.md`
- `skill-data/zero-builds.md`
- `skill-data/zero-diagnostics.md`
- `skill-data/zero-language.md`
- `skill-data/zero-packages.md`
- `skill-data/zero-stdlib.md`
- `skill-data/zero-testing.md`