vercel-labs--zerolang/docs/articles/primitives.md

The Pieces The Graph Stores

Zerolang exposes language pieces as graph facts and as .0 projection syntax. The graph stores the type and layout facts. The projection lets humans read them.

Scalar Values

Type	Purpose
Bool	Conditions and logical results.
i8 i16 i32 i64	Signed fixed-width integers.
u8 u16 u32 u64	Unsigned fixed-width integers.
usize isize	Pointer-sized integers.
f32 f64	Floating-point values.
char	Byte-sized character value for ASCII/parser/codec work.
String	Text value used by string literals and current I/O examples.
Void	Return type for functions that produce no useful value.

Integer literals support decimal, hexadecimal, binary, octal, _ separators, and optional suffixes such as _u8 or _usize. An unsuffixed integer literal adopts the type of a typed integer operand in arithmetic and comparisons when the value fits, so index + 1 and index < 10 work when index is usize. Out-of-range literals are rejected, so byte > 300 fails for a u8 operand.

let count: u32 = 0x12c_u32
let byte: u8 = 255
let page: usize = 4_096

Primitive numeric types do not implicitly narrow, widen, or change signedness. Use an explicit cast when the conversion is intentional.

let count: u32 = 300
let byte: u8 = count as u8

Absence

Maybe<T> represents an optional value:

let parsed: Maybe<u32> = std.args.parseU32(1)
if parsed.has {
    return parsed.value
}
return 0

.value reads require a visible .has guard or fallible handling. That rule is part of the graph semantics, not a formatter convention.

Fixed Storage And Views

Type form	Meaning
[N]T	Fixed-size array with N elements of T.
Span<T>	Read-only borrowed pointer plus length.
MutSpan<T>	Mutable borrowed pointer plus length.
ref<T>	Immutable reference.
mutref<T>	Mutable reference.

var scratch: [16]u8 = [0_u8; 16]
let bytes: Span<u8> = std.mem.span("hello")
let copied: usize = std.mem.copy(scratch, bytes)

These types are central to Zero's size and memory model. Helpers generally write into caller-owned storage so allocation behavior remains visible.

Fixed-size locals live in one stack frame per function, and a single function may declare at most 131072 bytes of locals. zero check reports MEM003 when a frame exceeds that limit; split the buffer into smaller buffers in helper functions so each frame stays within the limit, or process the data in fixed-size chunks. PageAlloc and GeneralAlloc handles type-check but do not lower to the direct backends yet, so they cannot replace frame-sized buffers today.

Ownership

Owned values use explicit ownership forms:

fn drop(self: mutref<Self>) -> Void {
    return
}

The canonical non-raising fn drop(self: mutref<Self>) -> Void shape lets the graph model cleanup without a hidden runtime cleanup registry. Owned resources, allocators, and cleanup behavior should be visible through graph inspection.

User Types

type Point {
    x: i32,
    y: i32,
}

Fields, defaults, and constructor-like projections are graph declarations and edges. Public type surfaces should stay explicit because agents rely on stable field and type facts.

Enums And Choices

enum Status {
    Pending,
    Ready,
}

Enums are named value sets. Choices and payload-bearing cases are represented as graph facts so match can be checked semantically.

Fallibility

Fallible functions use raises:

fn validate(ok: Bool) -> i32 raises [InvalidInput] {
    if !ok {
        raise InvalidInput
    }
    return 42
}

check propagates failure explicitly. There is no hidden exception system.

Compile-Time Values

Compile-time facts currently cover bounded integer, Bool, and enum static values. The metadata surface includes facts such as compileTime, target.pointerWidth, fieldType, and hasEnumCase.

Use zero inspect --json or zero check --json when an agent needs those facts for a patch.

Projection Examples

Projection syntax is for humans. The graph stores the same facts directly.

{
  "messages": [
    {
      "role": "user",
      "text": "what types does this helper use?"
    },
    {
      "role": "assistant",
      "text": "I’ll inspect the function facts and summarize the types."
    },
    {
      "role": "tools",
      "calls": [
        {
          "command": "zero query --fn add",
          "output": "fn add(x: i32, y: i32) -> i32\n  return x + y"
        }
      ]
    }
  ]
}

For manual review, export the projection:

zero export