Error message knowledge base: 259 curated patterns + omc_explain_error

Comprehensive error catalog in omnimcode-core/src/errors.rs covering
259 distinct error niches across 14 categories. LLMs catching OMC
errors call omc_explain_error(msg) and get back a structured dict
with what the error means, the typical cause, and the one-line fix —
no need to memorize the entire surface.

The catalog has two layers:
  (1) ~42 hand-written entries for the high-traffic / nuanced cases:
      did_you_mean dispatch, index-out-of-bounds, matmul shape
      mismatch, ragged 2D arrays, broadcast length mismatch, parser
      "Expected Semicolon" / "Expected identifier", JSON, base64,
      regex, etc. — each with cause + idiomatic fix.
  (2) 217 auto-generated entries, one per builtin that asserts arity.
      Same structure: pattern → category → explanation → fix-hint
      pointing at omc_help("<name>") for the right signature.

Three new introspection builtins:
  omc_explain_error(msg)   — match + structured dict back
  omc_error_categories()   — list buckets in the catalog
  omc_error_count()        — knowledge-base size (259 today)

The catalog itself is rendered by docs/render_full_errors() — wireable
into the next --gen-docs-style export.

Tests: 7 cases covering matched + unmatched lookups against the live
runtime, dispatch / arrays / linalg / substrate categories.

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

Author: RandomCoder-lab

examples/tests/test_error_catalog.omc

@@ -0,0 +1,103 @@
+# Error catalog — omc_explain_error pattern-matches runtime errors
+# against a curated knowledge base and returns structured remediation.
+#
+# LLMs catching OMC errors call this to get back actionable fixes
+# without having to memorize the 200+ error niches.
+
+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); }
+}
+
+# ---- omc_error_count ----
+
+fn test_error_count_substantial() {
+    h n = omc_error_count();
+    assert_true(n >= 40, "catalog has at least 40 patterns");
+}
+
+# ---- Pattern matching against a real runtime error ----
+
+fn test_explain_undefined_function() {
+    h err = "";
+    try {
+        h _ = arr_softmx([1.0]);  # typo
+    } catch e {
+        err = e;
+    }
+    h ex = omc_explain_error(err);
+    assert_eq(dict_get(ex, "matched"), 1, "pattern matched");
+    assert_eq(dict_get(ex, "category"), "dispatch", "category is dispatch");
+    assert_true(str_len(dict_get(ex, "fix")) > 0, "fix is non-empty");
+}
+
+fn test_explain_index_out_of_bounds() {
+    h err = "";
+    try {
+        h xs = [1, 2, 3];
+        h _ = arr_get(xs, 99);
+    } catch e {
+        err = e;
+    }
+    h ex = omc_explain_error(err);
+    assert_eq(dict_get(ex, "matched"), 1, "out-of-bounds matched");
+    assert_eq(dict_get(ex, "category"), "arrays", "category arrays");
+}
+
+fn test_explain_matmul_shape_mismatch() {
+    h err = "";
+    try {
+        h A = [[1, 2, 3]];
+        h B = [[1, 2]];  # wrong shape for matmul
+        h _ = arr_matmul(A, B);
+    } catch e {
+        err = e;
+    }
+    h ex = omc_explain_error(err);
+    assert_eq(dict_get(ex, "matched"), 1, "matmul shape matched");
+    assert_eq(dict_get(ex, "category"), "linalg", "linalg category");
+}
+
+# ---- Pattern matching on unknown error returns matched=0 ----
+
+fn test_explain_unknown_error() {
+    h ex = omc_explain_error("this error has no catalog entry whatsoever 12345 xyz");
+    assert_eq(dict_get(ex, "matched"), 0, "no match");
+    assert_true(str_len(dict_get(ex, "explanation")) > 0, "fallback explanation given");
+}
+
+# ---- omc_error_categories ----
+
+fn test_error_categories() {
+    h cats = omc_error_categories();
+    assert_true(arr_len(cats) >= 5, "at least 5 error categories");
+    h has_arrays = 0;
+    h has_dispatch = 0;
+    h i = 0;
+    while i < arr_len(cats) {
+        h c = arr_get(cats, i);
+        if c == "arrays" { has_arrays = 1; }
+        if c == "dispatch" { has_dispatch = 1; }
+        i = i + 1;
+    }
+    assert_eq(has_arrays, 1, "has 'arrays' category");
+    assert_eq(has_dispatch, 1, "has 'dispatch' category");
+}
+
+# ---- Substrate-aware error catalog ----
+
+fn test_explain_substrate_error() {
+    h err = "";
+    try {
+        h _ = arr_substrate_attention([[1, 2]]);  # missing K, V
+    } catch e {
+        err = e;
+    }
+    h ex = omc_explain_error(err);
+    assert_eq(dict_get(ex, "matched"), 1, "substrate attention error matched");
+}

omnimcode-core/src/compiler.rs

@@ -192,7 +192,7 @@ impl Compiler {
                         | "mod_pow" | "bit_count" | "bit_length"
                         | "digit_sum" | "digit_count"
                         | "arr_unique_count" | "arr_gcd" | "fnv1a_hash"
-                        | "is_instance"
+                        | "is_instance" | "omc_error_count"
                         // tape_* op constructors return node IDs (int)
                         | "tape_var" | "tape_const"
                         | "tape_add" | "tape_sub" | "tape_mul" | "tape_div"
@@ -278,6 +278,7 @@ impl Compiler {
                         // Introspection / discoverability surface
                         | "omc_list_builtins" | "omc_categories"
                         | "omc_did_you_mean" | "omc_unique_builtins"
+                        | "omc_error_categories"
                         // Forward-mode autograd duals (Track 2 — 2026-05-16)
                         | "dual" | "dual_add" | "dual_sub"
                         | "dual_mul" | "dual_div" | "dual_neg"

omnimcode-core/src/docs.rs

@@ -741,6 +741,27 @@ pub const BUILTINS: &[BuiltinDoc] = &[
         example: "omc_unique_builtins()  // [is_attractor, arr_substrate_attention, ...]",
         unique_to_omc: false,
     },
+    BuiltinDoc {
+        name: "omc_explain_error", category: "introspection",
+        signature: "(msg: string) -> dict",
+        description: "Pattern-match an error message against the curated catalog. Returns {matched, pattern, category, explanation, typical_cause, fix}.",
+        example: "try { arr_softmx([1.0]); } catch e { print(dict_get(omc_explain_error(e), \"fix\")); }",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_error_categories", category: "introspection",
+        signature: "() -> string[]",
+        description: "All distinct error categories in the catalog.",
+        example: "omc_error_categories()  // [dispatch, arrays, linalg, ...]",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_error_count", category: "introspection",
+        signature: "() -> int",
+        description: "Number of curated error patterns. The knowledge base size.",
+        example: "omc_error_count()  // 42+",
+        unique_to_omc: false,
+    },
 ];
 
 /// Look up a builtin by name. Returns None when there's no docs entry