chore: import upstream snapshot with attribution

docs/articles/primitives.md

@@ -0,0 +1,177 @@
+## 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.
+
+```zero
+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.
+
+```zero
+let count: u32 = 300
+let byte: u8 = count as u8
+```
+
+## Absence
+
+`Maybe<T>` represents an optional value:
+
+```zero
+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. |
+
+```zero
+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:
+
+```zero
+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
+
+```zero
+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
+
+```zero
+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`:
+
+```zero
+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.
+
+```json-render
+{
+  "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:
+
+```sh
+zero export
+```