feat(types): option (some/none) safety type (#53)

Types phase 3 — the option/result safety pair. result/ok/err/try shipped in
#46; this adds its companion option:

- some(v)   -> option   (present value; any i32-width scalar)
- none()    -> option   (empty; no magic -1 sentinel)
- is_some / is_none -> bool
- unwrap_or(o, fallback) -> int

A heap %Option = { i32 present, i32 value }, bare builtins guarded by find_fn
(a user fn of the same name still wins), gated by g_uses_option so unused
programs compile byte-identically — same idiom as result.

Wired: emit_call codegen + %Option decl (emit_decl) + g_uses_option (emit_core),
reseeded seed, vocabulary sync (header/JetBrains/TextMate), builtin docs +
inventory, and a self-asserting example (examples/library/optionresult.ludic +
feat_case). All suites green incl. golden renders byte-identical and the
bootstrap fixpoint.

Tagged-union enums (variant payloads + binding match + exhaustiveness) are the
deep type-system feature, split out to #56.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/language/builtins/fn-is_none.md

@@ -0,0 +1,24 @@
+---
+id: fn-is_none
+name: is_none
+category: builtins
+kind: builtin
+tokens: is_none
+sig: is_none(o: option) -> bool
+tip: True when an option is empty.
+order: 19
+---
+
+Returns true when an <code>option</code> is empty (it is <a href="fn-none"><code>none</code></a>). The complement of <a href="fn-is_some"><code>is_some</code></a>.
+
+Parameters:
+- `o` — the option to test
+
+```ludic
+program AI {
+  handler Step phase Update {
+    let target = none()
+    if is_none(target) { wander() }
+  }
+}
+```

docs/language/builtins/fn-is_some.md

@@ -0,0 +1,24 @@
+---
+id: fn-is_some
+name: is_some
+category: builtins
+kind: builtin
+tokens: is_some
+sig: is_some(o: option) -> bool
+tip: True when an option holds a value.
+order: 18
+---
+
+Returns true when an <code>option</code> holds a value (it is <a href="fn-some"><code>some</code></a>, not <a href="fn-none"><code>none</code></a>) — the guard before acting on an optional target or slot.
+
+Parameters:
+- `o` — the option to test
+
+```ludic
+program AI {
+  handler Step phase Update {
+    let target = none()
+    if is_some(target) { chase(unwrap_or(target, 0)) }
+  }
+}
+```

docs/language/builtins/fn-none.md

@@ -0,0 +1,24 @@
+---
+id: fn-none
+name: none
+category: builtins
+kind: builtin
+tokens: none
+sig: none() -> option
+tip: The empty option — a missing value.
+order: 17
+---
+
+The empty <code>option</code> — a missing value with no sentinel. Return it when there is nothing to give: no target, an empty slot, a lookup that missed. The caller distinguishes it from <a href="fn-some"><code>some</code></a> with <a href="fn-is_none"><code>is_none</code></a> / <a href="fn-is_some"><code>is_some</code></a>, or supplies a default with <a href="fn-unwrap_or"><code>unwrap_or</code></a>.
+
+```ludic
+program Slots {
+  function held(slot: int) -> option {
+    if slot < 0 { return none() }
+    return some(slot)
+  }
+  test "none is empty" {
+    expect_eq(is_none(held(0 - 1)), true)
+  }
+}
+```

docs/language/builtins/fn-some.md

@@ -0,0 +1,28 @@
+---
+id: fn-some
+name: some
+category: builtins
+kind: builtin
+tokens: some
+sig: some(v) -> option
+tip: Wrap a present value in an option.
+order: 16
+---
+
+Wraps a present value in an <code>option</code> — the value type that models <em>maybe a value</em> without a magic <code>-1</code> sentinel. An <code>option</code> is either <code>some(value)</code> (this) or <a href="fn-none"><code>none</code></a> (empty); test it with <a href="fn-is_some"><code>is_some</code></a> / <a href="fn-is_none"><code>is_none</code></a> and read it with <a href="fn-unwrap_or"><code>unwrap_or</code></a>. The payload is any <code>i32</code>-width scalar — <code>int</code>, <code>fixed</code>, <code>bool</code>, or <code>entity</code>.
+
+Parameters:
+- `v` — the present value
+
+```ludic
+program Targeting {
+  function nearest(count: int) -> option {
+    if count == 0 { return none() }
+    return some(count - 1)          # the nearest target index
+  }
+  test "some carries the value" {
+    let t = unwrap_or(nearest(3), 0 - 1)
+    expect_eq(t, 2)
+  }
+}
+```

docs/language/builtins/fn-unwrap_or.md

@@ -0,0 +1,24 @@
+---
+id: fn-unwrap_or
+name: unwrap_or
+category: builtins
+kind: builtin
+tokens: unwrap_or
+sig: unwrap_or(o: option, fallback) -> int
+tip: The option value, or a fallback if empty.
+order: 20
+---
+
+Reads an <code>option</code>: returns its value when it is <a href="fn-some"><code>some</code></a>, or <code>fallback</code> when it is <a href="fn-none"><code>none</code></a>. The safe, one-line way to get a usable value out of an option without a separate branch.
+
+Parameters:
+- `o` — the option to read
+- `fallback` — the value to use when the option is empty
+
+```ludic
+program Config {
+  handler Step phase Update {
+    let volume = unwrap_or(none(), 100)     # default to 100
+  }
+}
+```