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>

tools/docgen/inventory.json

@@ -48,7 +48,11 @@
     "fn-read_char",
     "fn-file_write",
     "fn-file_stdout",
-    "fn-file_stderr"
+    "fn-file_stderr",
+    "fn-ok",
+    "fn-err",
+    "fn-is_ok",
+    "fn-is_err"
   ],
   "collision": [
     "collision-rects",
@@ -72,7 +76,8 @@
     "kw-match",
     "kw-machine",
     "kw-state",
-    "kw-become"
+    "kw-become",
+    "kw-try"
   ],
   "ease": [
     "ease-in",

tools/editors/jetbrains/src/main/kotlin/io/ludic/ide/LudicTokens.kt

@@ -50,7 +50,7 @@ object LudicVocabulary {
     val STMT = setOf(
         "let", "return", "if", "else", "while", "for", "in", "spawn", "despawn",
         "enable", "disable", "match", "machine", "state", "become", "where",
-        "and", "or", "not", "break", "continue", "new", "emit", "cancel"
+        "and", "or", "not", "break", "continue", "new", "emit", "cancel", "try"
     )
     val PRIMITIVES = setOf("int", "long", "fixed", "bool", "entity", "string", "pointer", "byte", "words", "fixeds", "pointers", "Vector", "void")
     val PHASES = setOf("Start", "Input", "FixedUpdate", "Update", "LateUpdate", "Render")
@@ -65,6 +65,7 @@ object LudicVocabulary {
         "ui_tick", "ui_render", "ui_clicked", "ui_set_text", "ui_set_int", "ui_focus",
         "ui_focused", "ui_visible", "key", "reg", "set_reg", "self", "save", "load",
         "status", "print", "string", "quit", "panic", "assert",
+        "ok", "err", "is_ok", "is_err",
         // compiler intrinsics: the floor the Ludic-written runtime stands on
         "bytes", "words", "resize", "free", "fill",         "arg_count", "arg", "file_stderr", "file_stdout",
         "offset",

tools/editors/shared/ludic.tmLanguage.json

@@ -172,7 +172,7 @@
     },
     "keyword": {
       "patterns": [
-        { "name": "keyword.control.ludic", "match": "\\b(if|else|while|for|in|match|machine|become|return|spawn|despawn|enable|disable|where|break|continue|new)\\b" },
+        { "name": "keyword.control.ludic", "match": "\\b(if|else|while|for|in|match|machine|become|return|spawn|despawn|enable|disable|where|break|continue|new|try)\\b" },
         { "name": "keyword.operator.logical.ludic", "match": "\\b(and|or|not)\\b" },
         { "name": "keyword.other.clause.ludic", "match": "\\b(phase|query|on)\\b" },
         { "name": "keyword.other.ludic", "match": "\\b(import|extern)\\b" },
@@ -204,7 +204,7 @@
         {
           "comment": "the runtime surface — every name here resolves to rt_<name> in runtime/native",
           "name": "support.function.builtin.ludic",
-          "match": "\\b(min|max|abs|clamp|seed|rng_range|rng_chance|fixed|floor|map_size|map_row|tile|clear|present|fill_rect|frame_rect|put_px|text|text_int|font_load|text_ttf|text_w|text_h|image_load|draw_image|draw_image_scaled|draw_9slice|png_load|sprites_load|draw_sprite|draw_sprite_scaled|ui_build|ui_open|ui_tick|ui_render|ui_clicked|ui_set_text|ui_set_int|ui_focus|ui_focused|ui_visible|key|reg|set_reg|self|save|load|status|print|string|quit|panic|assert)\\b(?=\\s*\\()"
+          "match": "\\b(min|max|abs|clamp|seed|rng_range|rng_chance|fixed|floor|map_size|map_row|tile|clear|present|fill_rect|frame_rect|put_px|text|text_int|font_load|text_ttf|text_w|text_h|image_load|draw_image|draw_image_scaled|draw_9slice|png_load|sprites_load|draw_sprite|draw_sprite_scaled|ui_build|ui_open|ui_tick|ui_render|ui_clicked|ui_set_text|ui_set_int|ui_focus|ui_focused|ui_visible|key|reg|set_reg|self|save|load|status|print|string|quit|panic|assert|ok|err|is_ok|is_err)\\b(?=\\s*\\()"
         },
         {
           "comment": "compiler intrinsics — these lower straight to libc or the OS",

tools/editors/vscode/syntaxes/ludic.tmLanguage.json

@@ -172,7 +172,7 @@
     },
     "keyword": {
       "patterns": [
-        { "name": "keyword.control.ludic", "match": "\\b(if|else|while|for|in|match|machine|become|return|spawn|despawn|enable|disable|where|break|continue|new)\\b" },
+        { "name": "keyword.control.ludic", "match": "\\b(if|else|while|for|in|match|machine|become|return|spawn|despawn|enable|disable|where|break|continue|new|try)\\b" },
         { "name": "keyword.operator.logical.ludic", "match": "\\b(and|or|not)\\b" },
         { "name": "keyword.other.clause.ludic", "match": "\\b(phase|query|on)\\b" },
         { "name": "keyword.other.ludic", "match": "\\b(import|extern)\\b" },
@@ -204,7 +204,7 @@
         {
           "comment": "the runtime surface — every name here resolves to rt_<name> in runtime/native",
           "name": "support.function.builtin.ludic",
-          "match": "\\b(min|max|abs|clamp|seed|rng_range|rng_chance|fixed|floor|map_size|map_row|tile|clear|present|fill_rect|frame_rect|put_px|text|text_int|font_load|text_ttf|text_w|text_h|image_load|draw_image|draw_image_scaled|draw_9slice|png_load|sprites_load|draw_sprite|draw_sprite_scaled|ui_build|ui_open|ui_tick|ui_render|ui_clicked|ui_set_text|ui_set_int|ui_focus|ui_focused|ui_visible|key|reg|set_reg|self|save|load|status|print|string|quit|panic|assert)\\b(?=\\s*\\()"
+          "match": "\\b(min|max|abs|clamp|seed|rng_range|rng_chance|fixed|floor|map_size|map_row|tile|clear|present|fill_rect|frame_rect|put_px|text|text_int|font_load|text_ttf|text_w|text_h|image_load|draw_image|draw_image_scaled|draw_9slice|png_load|sprites_load|draw_sprite|draw_sprite_scaled|ui_build|ui_open|ui_tick|ui_render|ui_clicked|ui_set_text|ui_set_int|ui_focus|ui_focused|ui_visible|key|reg|set_reg|self|save|load|status|print|string|quit|panic|assert|ok|err|is_ok|is_err)\\b(?=\\s*\\()"
         },
         {
           "comment": "compiler intrinsics — these lower straight to libc or the OS",

tools/ludic-tools/ludic_syntax.h

@@ -68,7 +68,7 @@ static const char* LUDIC_KW_RESERVED[] = {
 static const char* LUDIC_KW_STMT[] = {
     "let","return","if","else","while","for","in","spawn","despawn",
     "enable","disable","match","machine","state","become","where",
-    "and","or","not","break","continue","new","emit","cancel", 0
+    "and","or","not","break","continue","new","emit","cancel","try", 0
 };
 static const char* LUDIC_TYPES[] = {
     "int","long","fixed","bool","entity","string","pointer","byte","words","fixeds","pointers","Vector","void", 0
@@ -143,6 +143,10 @@ static const LBuiltin LUDIC_BUILTINS[] = {
  {"quit","quit()","Stop the frame loop and exit."},
  {"panic","panic(msg: string)","Print `file:line: panic: msg` to stderr and abort (exit 1) — a located error, not a crash."},
  {"assert","assert(cond: bool, msg: string)","Abort with `file:line: assertion failed: msg` when cond is false — for programmer-bug invariants."},
+ {"ok","ok(v) -> result","Wrap a success payload (any i32-width scalar) in a result — the happy half of `try`/`else`."},
+ {"err","err(msg: string) -> result","Wrap a failure message in a result — the sad half, recovered by `try`/`else`."},
+ {"is_ok","is_ok(r: result) -> bool","True when a result carries a success payload."},
+ {"is_err","is_err(r: result) -> bool","True when a result carries a failure."},
  {0,0,0}
 };
 

tools/x/test.ludic

@@ -203,6 +203,7 @@ function cmd_test() -> int {
   spec_case("library/testing", "== 6 passed, 0 failed ==")
   spec_case("library/coverage", "== 3 passed, 0 failed ==")
   feat_case("library/errors", "", "5 10 0 7 1", "errors.ludic (assert guards an invariant, holds -> runs to the end; issue #8 success path)")
+  feat_case("library/recover", "", "2600 100 1 1 42 7", "recover.ludic (try/else recovers a result value + fallback, error binding, is_ok/is_err; issue #46)")
   panic_case()
   feat_case("library/logging", "", "0 5 2 1", "logging.ludic (Log levels, set_level/level threshold, structured fields)")
   # Os known-folders/arch and Fs.list read the BSD utsname/dirent layout, so