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>

tools/docgen/inventory.json

@@ -52,7 +52,12 @@
     "fn-ok",
     "fn-err",
     "fn-is_ok",
-    "fn-is_err"
+    "fn-is_err",
+    "fn-some",
+    "fn-none",
+    "fn-is_some",
+    "fn-is_none",
+    "fn-unwrap_or"
   ],
   "collision": [
     "collision-rects",

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

@@ -66,6 +66,7 @@ object LudicVocabulary {
         "ui_focused", "ui_visible", "key", "reg", "set_reg", "self", "save", "load",
         "status", "print", "string", "quit", "panic", "assert",
         "ok", "err", "is_ok", "is_err",
+        "some", "none", "is_some", "is_none", "unwrap_or",
         // 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

@@ -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|ok|err|is_ok|is_err)\\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|some|none|is_some|is_none|unwrap_or)\\b(?=\\s*\\()"
         },
         {
           "comment": "compiler intrinsics — these lower straight to libc or the OS",

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

@@ -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|ok|err|is_ok|is_err)\\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|some|none|is_some|is_none|unwrap_or)\\b(?=\\s*\\()"
         },
         {
           "comment": "compiler intrinsics — these lower straight to libc or the OS",

tools/ludic-tools/ludic_syntax.h

@@ -147,6 +147,11 @@ static const LBuiltin LUDIC_BUILTINS[] = {
  {"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."},
+ {"some","some(v) -> option","Wrap a present value (any i32-width scalar) in an option — the `has a value` case."},
+ {"none","none() -> option","The empty option — a missing value with no magic -1 sentinel."},
+ {"is_some","is_some(o: option) -> bool","True when an option holds a value."},
+ {"is_none","is_none(o: option) -> bool","True when an option is empty."},
+ {"unwrap_or","unwrap_or(o: option, fallback) -> int","The option's value, or fallback when it is empty."},
  {0,0,0}
 };
 

tools/x/test.ludic

@@ -196,6 +196,7 @@ function cmd_test() -> int {
   feat_case("library/bignum", "", "1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16", "bignum.ludic (BigInt arbitrary-precision + Decimal exact base-10 money)")
   feat_case("library/containers", "", "1 2 3 4 5 6 7 8 9 10 11 12 13 14", "containers.ludic (Dict string-keyed hash map + Set string set)")
   feat_case("library/numeric", "", "1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20", "numeric.ludic (Huge idle big-numbers + Angle wrapping radians + Percent clamped [0,1])")
+  feat_case("library/optionresult", "", "1 2 3 4 5 6 7 8 9 10 11 12", "optionresult.ludic (option some/none + result ok/err/try safety types)")
   feat_case("library/regex", "", "1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18", "regex.ludic (Regex match/find/groups/classes/quantifiers/replace + linear-time safety)")
   feat_case("library/grid", "", "1 2 3 4 5 6 7 8 9 10 11 12 13", "grid.ludic (Grid line/flood/line_of_sight + A* pathfinding over the tilemap)")
   feat_case("library/anim", "", "1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34", "anim.ludic (Anim frame/once/pingpong/cell + Tween progress/loop/yoyo/ease/number/round/point/tint)")