feat(errors): recoverable failures as values — try/else over ok/err results (#46)

A fallible function returns a `result` value, built with ok(payload) on success
or err(message) on failure. The caller recovers a value with `try EXPR else {
… }`: on ok the whole expression is the payload; on err the else block runs —
with the failure message bound to `error` — and its trailing expression supplies
the fallback. It is a plain branch on the result's tag: no exceptions, no hidden
control flow, nothing unwinds. is_ok(r) / is_err(r) classify without unwrapping.

Payloads are any i32-width scalar (int/fixed/bool/entity). The feature is
additive and only kicks in when ok/err/try are used, so untouched programs
compile byte-identically (verified) and the C-free bootstrap fixpoint holds.
Complements panic/assert from #8 (the unrecoverable half). The optional
top-level frame `recover` stays deferred (needs a frame-abort mechanism); the
full tagged-union/any generalization is tracked in #1.

Adds the `try` keyword and ok/err/is_ok/is_err builtins across the compiler,
the vocabulary header, JetBrains + TextMate/VSCode grammars, the docs inventory
and pages, examples/library/recover.ludic, and a regression case.

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

docs/language/builtins/fn-err.md

@@ -0,0 +1,28 @@
+---
+id: fn-err
+name: err
+category: builtins
+kind: builtin
+tokens: err
+sig: err(msg: string) -> result
+tip: Wrap a failure message in a result — the sad half, recovered by try/else.
+order: 13
+---
+
+Wraps a failure in a <code>result</code>, carrying a message that says what went wrong. It is the counterpart to <a href="fn-ok"><code>ok</code></a>: a fallible function (declared <code>-&gt; result</code>) returns <code>err("…")</code> on the sad path instead of crashing or returning a magic sentinel. The caller recovers with <a href="kw-try"><code>try</code></a>/<code>else</code> — the <code>else</code> block sees the message as <code>error</code> — or tests it with <a href="fn-is_err"><code>is_err</code></a>. Unlike <a href="fn-panic"><code>panic</code></a>, which aborts, <code>err</code> is a value: the program keeps running and chooses a fallback.
+
+Parameters:
+- `msg` — a message describing the failure (a string)
+
+```ludic
+program Config {
+  function volume(pct: int) -> result {
+    if pct < 0 or pct > 100 { return err("volume out of range") }
+    return ok(pct)
+  }
+  test "err drives the fallback" {
+    let v = try volume(150) else { 100 }    # clamp to a safe default
+    expect_eq(v, 100)
+  }
+}
+```

docs/language/builtins/fn-is_err.md

@@ -0,0 +1,28 @@
+---
+id: fn-is_err
+name: is_err
+category: builtins
+kind: builtin
+tokens: is_err
+sig: is_err(r: result) -> bool
+tip: True when a result carries a failure.
+order: 15
+---
+
+Tests a <code>result</code>'s tag: <code>true</code> when it was built with <a href="fn-err"><code>err</code></a>, <code>false</code> when it was built with <a href="fn-ok"><code>ok</code></a>. Use it to detect the failure case explicitly — for example to count or log failures — while <a href="kw-try"><code>try</code></a>/<code>else</code> handles recovering a value. It is the exact negation of <a href="fn-is_ok"><code>is_ok</code></a>.
+
+Parameters:
+- `r` — the result to test
+
+```ludic
+program Retry {
+  function step(n: int) -> result {
+    if n < 3 { return err("not ready") }
+    return ok(n)
+  }
+  test "is_err detects the failure case" {
+    expect(is_err(step(1)))
+    expect(not is_err(step(5)))
+  }
+}
+```

docs/language/builtins/fn-is_ok.md

@@ -0,0 +1,28 @@
+---
+id: fn-is_ok
+name: is_ok
+category: builtins
+kind: builtin
+tokens: is_ok
+sig: is_ok(r: result) -> bool
+tip: True when a result carries a success payload.
+order: 14
+---
+
+Tests a <code>result</code>'s tag: <code>true</code> when it was built with <a href="fn-ok"><code>ok</code></a>, <code>false</code> when it was built with <a href="fn-err"><code>err</code></a>. Use it when you want to branch on success without unwrapping the payload — the payload itself is recovered with <a href="kw-try"><code>try</code></a>/<code>else</code>. It is the exact negation of <a href="fn-is_err"><code>is_err</code></a>.
+
+Parameters:
+- `r` — the result to test
+
+```ludic
+program Check {
+  function find(x: int) -> result {
+    if x == 7 { return ok(x) }
+    return err("missing")
+  }
+  test "is_ok classifies without unwrapping" {
+    expect(is_ok(find(7)))
+    expect(not is_ok(find(3)))
+  }
+}
+```

docs/language/builtins/fn-ok.md

@@ -0,0 +1,30 @@
+---
+id: fn-ok
+name: ok
+category: builtins
+kind: builtin
+tokens: ok
+sig: ok(v) -> result
+tip: Wrap a success payload in a result — the happy half of try/else.
+order: 12
+---
+
+Wraps a success value in a <code>result</code> — the value type a fallible function returns. A <code>result</code> carries either a success payload (this) or a failure message (from <a href="fn-err"><code>err</code></a>), and a caller recovers it with <a href="kw-try"><code>try</code></a>/<code>else</code> or classifies it with <a href="fn-is_ok"><code>is_ok</code></a> / <a href="fn-is_err"><code>is_err</code></a>. A function that can fail declares <code>-&gt; result</code> and returns <code>ok(value)</code> on the happy path.
+
+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 success payload
+
+```ludic
+program Parse {
+  function to_digit(c: int) -> result {
+    if c >= 48 and c <= 57 { return ok(c - 48) }   # '0'..'9'
+    return err("not a digit")
+  }
+  test "ok carries the parsed value" {
+    let d = try to_digit(55) else { 0 }            # '7' -> 7
+    expect_eq(d, 7)
+  }
+}
+```

docs/language/builtins/fn-panic.md

@@ -11,7 +11,7 @@ order: 10
 
 Prints <code>file:line: panic: &lt;msg&gt;</code> to standard error and aborts the process with exit code 1. It turns "something went wrong" into a clear, located message a non-expert can act on — the opposite of a raw segfault or a silent wrong result. Use it for the unrecoverable case: a corrupt asset, a broken invariant, a branch that should be impossible. The source location is baked in at compile time, so the message always points at the exact call. For a guarded check that only aborts when a condition fails, use <a href="fn-assert"><code>assert</code></a>.
 
-Recoverable failures — a missing save, a bad network packet — are a different story: those should be values a game can fall back from rather than a `panic`. That value-carrying `try`/`else` path is sequenced after the type-system work (tagged unions); `panic` covers the programmer-bug half today.
+Recoverable failures — a missing save, a bad network packet — are a different story: those should be values a game can fall back from rather than a `panic`. That value-carrying path is <a href="kw-try"><code>try</code></a>/<code>else</code> over a <a href="fn-ok"><code>result</code></a>; `panic` covers the unrecoverable programmer-bug half.
 
 Parameters:
 - `msg` — a message describing what went wrong (a string)

docs/language/control/kw-try.md

@@ -0,0 +1,41 @@
+---
+id: kw-try
+name: try
+category: control
+kind: keyword
+tokens: try
+sig: try EXPR else { … }
+tip: Recover a fallible result as a value, with a fallback — no exceptions, no unwinding.
+order: 12
+---
+
+A <code>try EXPR else { … }</code> expression recovers a fallible operation without exceptions or unwinding. <code>EXPR</code> evaluates to a <a href="fn-ok"><code>result</code></a> — a value carrying either a success payload (from <a href="fn-ok"><code>ok</code></a>) or a failure message (from <a href="fn-err"><code>err</code></a>). When it is <code>ok</code>, the whole <code>try</code> expression <em>is</em> that payload and the <code>else</code> block is skipped. When it is <code>err</code>, the <code>else</code> block runs and its trailing expression supplies the fallback value; inside the block the failure message is bound to <code>error</code>, so you can log or branch on it. It is a plain branch on the result's tag — the happy path stays one line, there is no hidden control flow, and nothing unwinds the stack.
+
+The payload is an <code>i32</code>-width scalar (<code>int</code>, <code>fixed</code>, <code>bool</code>, or <code>entity</code>) — the common case of "a number or nothing". For richer payloads and full pattern-matching over tagged unions, see the type-system work (#1).
+
+```ludic
+program SaveLoad {
+  # a fallible op returns a result: ok(payload) or err(message)
+  function load_score(slot: int) -> result {
+    if slot == 1 { return ok(4200) }
+    return err("no save in that slot")
+  }
+
+  test "ok yields the payload, err falls back" {
+    let a = try load_score(1) else { 0 }      # 4200
+    let b = try load_score(9) else { 0 }      # 0 (fallback)
+    expect_eq(a, 4200)
+    expect_eq(b, 0)
+  }
+
+  test "the fallback can read the failure via `error`" {
+    var logged = 0
+    let score = try load_score(3) else {
+      if error == "no save in that slot" { logged = 1 }
+      0                                        # trailing expression = the fallback
+    }
+    expect_eq(score, 0)
+    expect_eq(logged, 1)
+  }
+}
+```