introspection: +9 helper builtins + 14 tests

Compact-form helpers for LLM round-trips that want less data:

  omc_help_brief(name)       -> string  (sig + desc, no example)
  omc_help_signature(name)   -> string  (just the signature)
  omc_help_example(name)     -> string  (just the example)
  omc_help_category(name)    -> string  (just the category)
  omc_is_unique(name)        -> int     (1 if OMC-unique)
  omc_count_in_category(c)   -> int     (population count)
  omc_random_builtin()       -> string  (random name)
  omc_random_unique_builtin() -> string (random OMC-unique name)
  omc_token_vocab_dump(n?)   -> string  (first N vocab entries)

For an LLM the workflow becomes:
  - omc_help_signature for quick disambiguation
  - omc_help_example when stuck
  - omc_help_brief for batch exploration
  - omc_random_unique_builtin to discover differentiators

Tests: 14 covering each helper + known/unknown lookup, category-
filter sanity, vocab-dump default vs explicit size.

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

Author: RandomCoder-lab

OMC_REFERENCE.md

@@ -2,7 +2,7 @@
 
 Auto-generated from `omnimcode-core/src/docs.rs`. Run `omc --gen-docs > OMC_REFERENCE.md` to regenerate.
 
-**Total documented builtins**: 619
+**Total documented builtins**: 628
 
 **OMC-unique**: 63 (no direct Python/NumPy equivalent — these are why you reach for OMC over numpy)
 
@@ -23,8 +23,8 @@ Auto-generated from `omnimcode-core/src/docs.rs`. Run `omc --gen-docs > OMC_REFE
 - [json](#json) (2 builtins)
 - [stdlib](#stdlib) (26 builtins)
 - [exceptions](#exceptions) (2 builtins)
-- [introspection](#introspection) (22 builtins)
-- [tokenizer](#tokenizer) (16 builtins)
+- [introspection](#introspection) (30 builtins)
+- [tokenizer](#tokenizer) (17 builtins)
 - [code_intel](#code_intel) (16 builtins)
 - [llm_workflow](#llm_workflow) (7 builtins)
 - [math](#math) (82 builtins)
@@ -4510,6 +4510,86 @@ Substring search across name + description. Find what you don't know the name of
 omc_search_builtins("softmax")  // ["arr_softmax"]
 ```
 
+### `omc_help_brief`
+
+**Signature**: `(name: string) -> string`
+
+Compact help: signature + description only (no example). For dense scan.
+
+```omc
+omc_help_brief("arr_softmax")
+```
+
+### `omc_help_signature`
+
+**Signature**: `(name: string) -> string`
+
+Just the signature string. Compactest possible.
+
+```omc
+omc_help_signature("arr_get")  // "(arr, index) -> any"
+```
+
+### `omc_help_example`
+
+**Signature**: `(name: string) -> string`
+
+Just the example for a builtin.
+
+```omc
+omc_help_example("arr_softmax")
+```
+
+### `omc_help_category`
+
+**Signature**: `(name: string) -> string`
+
+Just the category for a builtin.
+
+```omc
+omc_help_category("arr_softmax")  // "ml_kernels"
+```
+
+### `omc_is_unique`
+
+**Signature**: `(name: string) -> int`
+
+1 if the builtin is flagged unique_to_omc.
+
+```omc
+omc_is_unique("is_attractor")  // 1
+```
+
+### `omc_count_in_category`
+
+**Signature**: `(category: string) -> int`
+
+Builtin count in a given category.
+
+```omc
+omc_count_in_category("substrate")  // ~25
+```
+
+### `omc_random_builtin`
+
+**Signature**: `() -> string`
+
+A random builtin name. Useful for exploring or fuzzing.
+
+```omc
+omc_random_builtin()  // "arr_zip"
+```
+
+### `omc_random_unique_builtin`
+
+**Signature**: `() -> string`
+
+A random OMC-unique builtin name. For learning the differentiators.
+
+```omc
+omc_random_unique_builtin()  // "arr_substrate_attention"
+```
+
 ### `cleanup_array`
 
 **Signature**: `(...) -> any`
@@ -4694,6 +4774,16 @@ omc_token_byte_savings("arr_softmax")  // 10 (11 bytes -> 1 token)
 omc_token_compress_pct("arr_softmax")  // ~90.9
 ```
 
+### `omc_token_vocab_dump`
+
+**Signature**: `(n?: int) -> string`
+
+First N entries of the token vocabulary as numbered list. Default n=50.
+
+```omc
+omc_token_vocab_dump(10)  // first 10 entries
+```
+
 ---
 
 ## code_intel

examples/tests/test_introspection_helpers.omc

@@ -0,0 +1,81 @@
+# Tests for the new introspection helper builtins.
+
+fn assert_eq(actual, expected, msg) {
+    if actual != expected {
+        test_record_failure(msg + ": expected " + to_string(expected) + " got " + to_string(actual));
+    }
+}
+
+fn assert_true(cond, msg) { if !cond { test_record_failure(msg); } }
+
+fn test_help_brief() {
+    h s = omc_help_brief("arr_softmax");
+    assert_true(str_len(s) > 10, "brief non-empty");
+    assert_true(re_match("arr_softmax", s) == 1, "mentions name");
+}
+
+fn test_help_brief_unknown() {
+    h s = omc_help_brief("zzz_no_such");
+    assert_true(re_match("not in registry", s) == 1, "explains miss");
+}
+
+fn test_help_signature() {
+    h s = omc_help_signature("arr_softmax");
+    assert_true(str_len(s) > 0, "has signature");
+    assert_true(re_match("float", s) == 1, "mentions float");
+}
+
+fn test_help_signature_unknown() {
+    h s = omc_help_signature("doesnotexist");
+    assert_eq(s, "", "empty for unknown");
+}
+
+fn test_help_example() {
+    h s = omc_help_example("arr_softmax");
+    assert_true(str_len(s) > 0, "non-empty");
+}
+
+fn test_help_category() {
+    assert_eq(omc_help_category("arr_softmax"), "ml_kernels", "ml_kernels");
+    assert_eq(omc_help_category("is_attractor"), "substrate", "substrate");
+}
+
+fn test_is_unique_yes() {
+    assert_eq(omc_is_unique("is_attractor"), 1, "is_attractor unique");
+}
+
+fn test_is_unique_no() {
+    assert_eq(omc_is_unique("arr_push"), 0, "arr_push not unique");
+}
+
+fn test_count_in_category_substrate() {
+    h n = omc_count_in_category("substrate");
+    assert_true(n >= 5, "substrate has many");
+}
+
+fn test_count_in_category_unknown() {
+    h n = omc_count_in_category("nonexistent_xyz");
+    assert_eq(n, 0, "unknown → 0");
+}
+
+fn test_random_builtin_returns_name() {
+    h n = omc_random_builtin();
+    assert_true(str_len(n) > 0, "non-empty");
+}
+
+fn test_random_unique_is_unique() {
+    h n = omc_random_unique_builtin();
+    assert_eq(omc_is_unique(n), 1, "is unique");
+}
+
+fn test_vocab_dump_default() {
+    h s = omc_token_vocab_dump();
+    assert_true(str_len(s) > 100, "has many entries");
+}
+
+fn test_vocab_dump_small() {
+    h s = omc_token_vocab_dump(5);
+    # 5 entries means 5 numbered lines
+    h lines = str_split(s, "\n");
+    assert_true(arr_len(lines) >= 5, "at least 5 lines");
+}

omnimcode-core/src/compiler.rs

@@ -203,6 +203,7 @@ impl Compiler {
                         | "omc_unique_count"
                         | "omc_token_byte_savings" | "omc_remember"
                         | "omc_recall_matches" | "omc_hbit_hash"
+                        | "omc_is_unique" | "omc_count_in_category"
                         // tape_* op constructors return node IDs (int)
                         | "tape_var" | "tape_const"
                         | "tape_add" | "tape_sub" | "tape_mul" | "tape_div"

omnimcode-core/src/docs.rs

@@ -1123,6 +1123,69 @@ pub const BUILTINS: &[BuiltinDoc] = &[
         example: "omc_id(src)  // \"omcid-12345-abcd\"",
         unique_to_omc: true,
     },
+    BuiltinDoc {
+        name: "omc_token_vocab_dump", category: "tokenizer",
+        signature: "(n?: int) -> string",
+        description: "First N entries of the token vocabulary as numbered list. Default n=50.",
+        example: "omc_token_vocab_dump(10)  // first 10 entries",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_help_brief", category: "introspection",
+        signature: "(name: string) -> string",
+        description: "Compact help: signature + description only (no example). For dense scan.",
+        example: "omc_help_brief(\"arr_softmax\")",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_help_signature", category: "introspection",
+        signature: "(name: string) -> string",
+        description: "Just the signature string. Compactest possible.",
+        example: "omc_help_signature(\"arr_get\")  // \"(arr, index) -> any\"",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_help_example", category: "introspection",
+        signature: "(name: string) -> string",
+        description: "Just the example for a builtin.",
+        example: "omc_help_example(\"arr_softmax\")",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_help_category", category: "introspection",
+        signature: "(name: string) -> string",
+        description: "Just the category for a builtin.",
+        example: "omc_help_category(\"arr_softmax\")  // \"ml_kernels\"",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_is_unique", category: "introspection",
+        signature: "(name: string) -> int",
+        description: "1 if the builtin is flagged unique_to_omc.",
+        example: "omc_is_unique(\"is_attractor\")  // 1",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_count_in_category", category: "introspection",
+        signature: "(category: string) -> int",
+        description: "Builtin count in a given category.",
+        example: "omc_count_in_category(\"substrate\")  // ~25",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_random_builtin", category: "introspection",
+        signature: "() -> string",
+        description: "A random builtin name. Useful for exploring or fuzzing.",
+        example: "omc_random_builtin()  // \"arr_zip\"",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_random_unique_builtin", category: "introspection",
+        signature: "() -> string",
+        description: "A random OMC-unique builtin name. For learning the differentiators.",
+        example: "omc_random_unique_builtin()  // \"arr_substrate_attention\"",
+        unique_to_omc: false,
+    },
     // ---- Auto-generated docs for previously-undocumented builtins ----
     // Each entry covers one runtime builtin that lacked introspection.
     // Stubs are conservative — refine as you learn the actual signatures.

omnimcode-core/src/interpreter.rs

@@ -7793,6 +7793,98 @@ impl Interpreter {
                 }
                 Ok(Value::dict_from(map))
             }
+            "omc_token_vocab_dump" => {
+                // First N entries of vocab as a numbered list.
+                let n = if !args.is_empty() {
+                    self.eval_expr(&args[0])?.to_int().max(0) as usize
+                } else { 50 };
+                let mut s = String::new();
+                let len = crate::tokenizer::TOKEN_DICT.len().min(n);
+                for (i, entry) in crate::tokenizer::TOKEN_DICT.iter().take(len).enumerate() {
+                    let display = entry.replace('\n', "\\n").replace('\t', "\\t");
+                    s.push_str(&format!("{:4}: {:?}\n", i, display));
+                }
+                Ok(Value::String(s))
+            }
+            "omc_help_brief" => {
+                // Just signature + one-line description (no example). Useful
+                // when the LLM wants a compact view across many builtins.
+                if args.is_empty() {
+                    return Err("omc_help_brief requires (name)".to_string());
+                }
+                let name = self.eval_expr(&args[0])?.to_display_string();
+                match crate::docs::lookup(&name) {
+                    Some(d) => Ok(Value::String(format!(
+                        "{} :: {}\n  {}", d.name, d.signature, d.description
+                    ))),
+                    None => Ok(Value::String(format!("{}: not in registry", name))),
+                }
+            }
+            "omc_help_signature" => {
+                // Just the signature string. Compactest possible.
+                if args.is_empty() {
+                    return Err("omc_help_signature requires (name)".to_string());
+                }
+                let name = self.eval_expr(&args[0])?.to_display_string();
+                match crate::docs::lookup(&name) {
+                    Some(d) => Ok(Value::String(d.signature.to_string())),
+                    None => Ok(Value::String(String::new())),
+                }
+            }
+            "omc_help_example" => {
+                if args.is_empty() {
+                    return Err("omc_help_example requires (name)".to_string());
+                }
+                let name = self.eval_expr(&args[0])?.to_display_string();
+                match crate::docs::lookup(&name) {
+                    Some(d) => Ok(Value::String(d.example.to_string())),
+                    None => Ok(Value::String(String::new())),
+                }
+            }
+            "omc_help_category" => {
+                if args.is_empty() {
+                    return Err("omc_help_category requires (name)".to_string());
+                }
+                let name = self.eval_expr(&args[0])?.to_display_string();
+                match crate::docs::lookup(&name) {
+                    Some(d) => Ok(Value::String(d.category.to_string())),
+                    None => Ok(Value::String(String::new())),
+                }
+            }
+            "omc_is_unique" => {
+                // 1 if name is OMC-unique (no Python equivalent).
+                if args.is_empty() {
+                    return Err("omc_is_unique requires (name)".to_string());
+                }
+                let name = self.eval_expr(&args[0])?.to_display_string();
+                match crate::docs::lookup(&name) {
+                    Some(d) => Ok(Value::HInt(HInt::new(if d.unique_to_omc { 1 } else { 0 }))),
+                    None => Ok(Value::HInt(HInt::new(0))),
+                }
+            }
+            "omc_count_in_category" => {
+                if args.is_empty() {
+                    return Err("omc_count_in_category requires (category)".to_string());
+                }
+                let cat = self.eval_expr(&args[0])?.to_display_string();
+                let count = crate::docs::BUILTINS.iter()
+                    .filter(|b| b.category == cat).count() as i64;
+                Ok(Value::HInt(HInt::new(count)))
+            }
+            "omc_random_builtin" => {
+                // Random builtin name. Useful for fuzzing or exploring.
+                let idx = (self.rng_next() % (crate::docs::BUILTINS.len() as u64)) as usize;
+                Ok(Value::String(crate::docs::BUILTINS[idx].name.to_string()))
+            }
+            "omc_random_unique_builtin" => {
+                let uniq: Vec<&str> = crate::docs::BUILTINS.iter()
+                    .filter(|b| b.unique_to_omc).map(|b| b.name).collect();
+                if uniq.is_empty() {
+                    return Ok(Value::String(String::new()));
+                }
+                let idx = (self.rng_next() % (uniq.len() as u64)) as usize;
+                Ok(Value::String(uniq[idx].to_string()))
+            }
             "omc_search_builtins" => {
                 // Substring search across name + description. Returns
                 // matching names. Useful when you don't know what