LLM ergonomics batch: ||/&&, --test-all + --json, std/test, signature

search, onboarding token

Five wins for both human and LLM authors of OMC, addressing the
specific friction points encountered while writing OMC code today.

1. Lexer: `||` and `&&` now alias keyword `or` and `and`. Single
   `|`/`&` still parse as bit-OR/AND. Every C-family programmer
   (and every LLM trained on them) reaches for `||` first; the
   silent BitOr parse error was the largest single footgun.

2. CLI: --test-all DIR runs every test_*.omc under DIR with a
   one-line-per-file pass/fail summary + overall total. Default
   DIR is `examples/tests/`. With --json, both --test and
   --test-all emit JSONL per-test results + a summary line for
   machine consumption (CI, LLM iteration loops).
   Verified: 66 files / 1000 tests / 997 pass / 3 fail
   (heal_pass requires OMC_HEAL=1 — surfaced as a real diagnostic).

3. examples/lib/test.omc: canonical assert_eq, assert_ne,
   assert_true, assert_false, assert_near, assert_throws,
   assert_throws_with, assert_contains, assert_len. The 64-copy
   assert_eq cluster (largest in the codebase per omc-grep) can
   now be deduplicated as files are touched. test_stdlib_test.omc
   exercises 9/9 ok.

4. omc_find_by_signature(pattern, max?) builtin: case-insensitive
   substring match against every builtin's signature string. Lets
   LLMs discover by intent ("-> float[]", "string, int") instead
   of name-guessing. Returns [{name, signature, category,
   description}, ...].

5. LLM-onboarding token (examples/tools/gen_onboarding_token.omc):
   produces docs/onboarding_token.json — a 77.6 KB substrate-
   signed envelope containing:
     - 41.7 KB bootstrap_pack (the existing markdown intro)
     - manifest of 193 lib fns: {lib, name, canonical_hash,
       attractor, signature}
     - kind=7 substrate-signed envelope so receivers can verify
       integrity without a shared key

   The consumer demo (examples/tools/consume_onboarding_token.omc)
   verifies the envelope signature, parses the bundle, prints
   manifest samples, and demonstrates downstream
   omc_find_by_signature discovery. One artifact you can drop
   into a fresh LLM's context and it knows OMC.

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

Author: RandomCoder-lab

docs/onboarding_token.json

@@ -0,0 +1,102 @@
+# std/test — canonical assertion helpers for OMC test suites.
+#
+# Before this library, every test file under examples/tests/ defined
+# its own assert_eq / assert_true. omc-grep counted 64 copies of
+# assert_eq alone (the largest cluster in the codebase).
+#
+# To use:
+#   from "lib/test.omc" import assert_eq, assert_true, assert_near, assert_throws
+#
+# Or import the whole module:
+#   import "lib/test.omc"
+#
+# Conventions:
+#   - msg is the diagnostic shown when an assertion fails
+#   - test_record_failure is the OMC test-runner hook that flags a fail
+#   - assertions short-circuit (return) after recording so a single
+#     bad assertion doesn't cascade into noise
+
+fn assert_eq(actual, expected, msg) {
+    if actual != expected {
+        test_record_failure(msg + ": expected " + to_string(expected) + " got " + to_string(actual));
+    }
+}
+
+fn assert_ne(actual, unexpected, msg) {
+    if actual == unexpected {
+        test_record_failure(msg + ": expected != " + to_string(unexpected) + " but got equal");
+    }
+}
+
+fn assert_true(cond, msg) {
+    if !cond {
+        test_record_failure(msg);
+    }
+}
+
+fn assert_false(cond, msg) {
+    if cond {
+        test_record_failure(msg + ": expected false, got true");
+    }
+}
+
+# Float equality within an epsilon tolerance. Default eps = 1e-9
+# (tight for typical FP work; pass a looser eps for ML/stats tests).
+fn assert_near(actual, expected, eps, msg) {
+    h diff = actual - expected;
+    h abs_diff = diff;
+    if abs_diff < 0.0 { abs_diff = 0.0 - abs_diff; }
+    if abs_diff > eps {
+        test_record_failure(msg + ": expected ~" + to_string(expected) + " (eps=" + to_string(eps) + ") got " + to_string(actual));
+    }
+}
+
+# Assertion: invoking nullary fn body_fn raises ANY error.
+# Use for "this should fail" tests without coupling to the exact
+# error message.
+fn assert_throws(body_fn, msg) {
+    h threw = false;
+    try {
+        body_fn();
+    } catch e {
+        threw = true;
+    }
+    if !threw {
+        test_record_failure(msg + ": expected to throw, completed normally");
+    }
+}
+
+# Like assert_throws but also requires the error message to contain
+# a given substring. Use to assert a specific failure mode.
+fn assert_throws_with(body_fn, expected_substr, msg) {
+    h threw = false;
+    h err_text = "";
+    try {
+        body_fn();
+    } catch e {
+        threw = true;
+        err_text = e;
+    }
+    if !threw {
+        test_record_failure(msg + ": expected to throw, completed normally");
+        return;
+    }
+    if re_match(expected_substr, err_text) != 1 {
+        test_record_failure(msg + ": error did not contain `" + expected_substr + "`; got: " + err_text);
+    }
+}
+
+# Convenience: assert string contains substring.
+fn assert_contains(haystack, needle, msg) {
+    if re_match(needle, haystack) != 1 {
+        test_record_failure(msg + ": expected `" + needle + "` in `" + haystack + "`");
+    }
+}
+
+# Convenience: assert array length.
+fn assert_len(arr, expected_len, msg) {
+    h actual = arr_len(arr);
+    if actual != expected_len {
+        test_record_failure(msg + ": expected len " + to_string(expected_len) + " got " + to_string(actual));
+    }
+}

examples/lib/test.omc

@@ -0,0 +1,52 @@
+# Tests for examples/lib/test.omc — the canonical assertion helpers.
+# (Meta-test: tests that the test library does what it says.)
+
+from "examples/lib/test.omc" import assert_eq, assert_ne, assert_true, assert_false, assert_near, assert_throws, assert_throws_with, assert_contains, assert_len;
+
+fn test_assert_eq_pass() {
+    assert_eq(1 + 1, 2, "math");
+    assert_eq("hi", "hi", "string");
+    assert_eq(arr_len([1, 2, 3]), 3, "len");
+}
+
+fn test_assert_ne_pass() {
+    assert_ne(1, 2, "diff");
+    assert_ne("a", "b", "str diff");
+}
+
+fn test_assert_true_pass() {
+    assert_true(true, "literal true");
+    assert_true(1 == 1, "eq result");
+    assert_true(arr_len([1]) > 0, "nonempty");
+}
+
+fn test_assert_false_pass() {
+    assert_false(false, "literal false");
+    assert_false(1 == 2, "neq result");
+}
+
+fn test_assert_near_pass() {
+    assert_near(0.1 + 0.2, 0.3, 1e-9, "fp drift");
+    assert_near(1.0, 1.0001, 0.001, "loose eps");
+}
+
+fn test_assert_throws_pass() {
+    assert_throws(fn() { h _ = error("boom"); }, "should throw");
+}
+
+fn test_assert_throws_with_pass() {
+    assert_throws_with(
+        fn() { h _ = error("specific failure mode"); },
+        "specific",
+        "matches substring"
+    );
+}
+
+fn test_assert_contains_pass() {
+    assert_contains("hello world", "world", "substring");
+}
+
+fn test_assert_len_pass() {
+    assert_len([1, 2, 3], 3, "array len");
+    assert_len([], 0, "empty");
+}

examples/tests/test_stdlib_test.omc

@@ -0,0 +1,78 @@
+# Consume an OMC onboarding token.
+#
+# This is the receiver-side flow for a new-to-OMC LLM (or any agent
+# that wasn't pre-loaded with the language).
+#
+# Steps:
+#   1. Read the substrate-signed envelope from docs/onboarding_token.json
+#   2. Verify the substrate signature (content_hash must equal the
+#      recomputed canonical hash of the inner content — defends
+#      against bundle tampering, no shared key needed)
+#   3. Parse the inner bundle
+#   4. Print a summary so a downstream LLM knows what's available
+#   5. Demonstrate one round-trip: pick a fn from the manifest,
+#      fetch its full source via the registry / kernel
+#
+# Run from the OMC repo root:
+#   omnimcode-standalone examples/tools/consume_onboarding_token.omc
+
+fn main() {
+    h wire = read_file("docs/onboarding_token.json");
+    h envelope = omc_msg_deserialize(wire);
+
+    # Step 1: verify the substrate signature.
+    h check = omc_msg_verify(envelope);
+    h valid = dict_get(check, "valid");
+    if valid != 1 {
+        print("FAIL: envelope signature invalid — bundle was tampered with.");
+        print(concat_many("  expected_hash = ", to_string(dict_get(check, "expected_hash"))));
+        print(concat_many("  actual_hash   = ", to_string(dict_get(check, "actual_hash"))));
+        return;
+    }
+    print("[OK] substrate envelope signature verified");
+    print(concat_many("     content_hash = ", to_string(dict_get(envelope, "content_hash"))));
+    print(concat_many("     attractor    = ", to_string(dict_get(envelope, "attractor"))));
+
+    # Step 2: parse the inner bundle.
+    h content = dict_get(check, "content");
+    h bundle = json_parse(content);
+    print("");
+    print(concat_many("Bundle version  : ", dict_get(bundle, "version")));
+    print(concat_many("Bootstrap pack  : ", to_string(dict_get(bundle, "bootstrap_bytes")), " bytes"));
+    print(concat_many("Library fns     : ", to_string(dict_get(bundle, "fn_count"))));
+
+    # Step 3: show a sample of the manifest.
+    h manifest = dict_get(bundle, "lib_manifest");
+    print("");
+    print("Sample manifest entries (first 5):");
+    h i = 0;
+    while i < 5 && i < arr_len(manifest) {
+        h entry = arr_get(manifest, i);
+        print(concat_many(
+            "  ", dict_get(entry, "lib"),
+            "  ", dict_get(entry, "signature"),
+            "  hash=", to_string(dict_get(entry, "canonical_hash"))
+        ));
+        i = i + 1;
+    }
+
+    # Step 4: show that the LLM can now ask "do you have fns returning float[]?"
+    print("");
+    print("LLM discovery query: omc_find_by_signature(\"-> float[]\", 3)");
+    h hits = omc_find_by_signature("-> float[]", 3);
+    i = 0;
+    while i < arr_len(hits) {
+        h r = arr_get(hits, i);
+        print(concat_many("  ", dict_get(r, "name"), " :: ", dict_get(r, "signature")));
+        i = i + 1;
+    }
+
+    print("");
+    print("Onboarding complete. A downstream LLM now knows:");
+    print("  * the language's bootstrap pack (categories, idioms, gotchas)");
+    print("  * every standard-library fn's canonical address");
+    print("  * how to discover builtins by signature");
+    print("  * how to verify the bundle came from the expected substrate");
+}
+
+main();

examples/tools/consume_onboarding_token.omc

@@ -0,0 +1,146 @@
+# Generate the OMC onboarding bundle.
+#
+# Output: a single JSON file an LLM can ingest cold and immediately
+# be productive in OMC. The bundle is substrate-signed (integrity
+# verifiable without a shared key) and references registry/library
+# functions by canonical hash (alpha-rename invariant).
+#
+# Contents:
+#   * version            — build identifier
+#   * bootstrap_pack     — the ~20KB markdown intro from omc_bootstrap_pack()
+#   * lib_manifest       — for every fn in examples/lib/ :
+#                          {name, canonical_hash, attractor, signature_first_line}
+#   * substrate_envelope — substrate-signed wrapper over the above
+#                          (sender=0 = kernel-level signing)
+#
+# Run from the OMC repo root:
+#   omnimcode-standalone examples/tools/gen_onboarding_token.omc > docs/onboarding_token.json
+#
+# Or pipe directly into another tool. The output is one line of JSON.
+
+fn extract_fns_from_file(path) {
+    h src = read_file(path);
+    h fns = [];
+    h i = 0;
+    h n = str_len(src);
+    while i < n {
+        # Look for "fn " at line start or after whitespace.
+        if str_slice(src, i, i + 3) == "fn " && (i == 0 || str_slice(src, i - 1, i) == "\n" || str_slice(src, i - 1, i) == " ") {
+            # Find the opening brace.
+            h j = i;
+            while j < n && str_slice(src, j, j + 1) != "{" { j = j + 1; }
+            if j >= n { i = i + 1; }
+            else {
+                # Track brace depth.
+                h depth = 0;
+                h k = j;
+                while k < n {
+                    h c = str_slice(src, k, k + 1);
+                    if c == "{" { depth = depth + 1; }
+                    elif c == "}" {
+                        depth = depth - 1;
+                        if depth == 0 { k = k + 1; break; }
+                    }
+                    k = k + 1;
+                }
+                if depth == 0 {
+                    arr_push(fns, str_slice(src, i, k));
+                    i = k;
+                } else {
+                    i = i + 1;
+                }
+            }
+        } else {
+            i = i + 1;
+        }
+    }
+    return fns;
+}
+
+fn fn_name_of(src) {
+    # Pull NAME from "fn NAME(...)". skip "fn " (3 chars).
+    h after = str_slice(src, 3, str_len(src));
+    h i = 0;
+    while i < str_len(after) {
+        h c = str_slice(after, i, i + 1);
+        if c == "(" || c == " " { break; }
+        i = i + 1;
+    }
+    return str_slice(after, 0, i);
+}
+
+fn signature_first_line(src) {
+    # Return the "fn NAME(...)" signature only.
+    h i = 0;
+    while i < str_len(src) && str_slice(src, i, i + 1) != "{" { i = i + 1; }
+    return str_trim(str_slice(src, 0, i));
+}
+
+fn build_lib_manifest() {
+    h libs = [
+        "examples/lib/np.omc",
+        "examples/lib/pd.omc",
+        "examples/lib/sklearn.omc",
+        "examples/lib/torch.omc",
+        "examples/lib/requests.omc",
+        "examples/lib/sqlite.omc",
+        "examples/lib/substrate.omc",
+        "examples/lib/harmonic_anomaly.omc",
+        "examples/lib/harmonic_clustering.omc",
+        "examples/lib/harmonic_recommend.omc",
+        "examples/lib/test.omc",
+    ];
+    h manifest = [];
+    h i = 0;
+    while i < arr_len(libs) {
+        h path = arr_get(libs, i);
+        h fns = extract_fns_from_file(path);
+        h j = 0;
+        while j < arr_len(fns) {
+            h fn_src = arr_get(fns, j);
+            h entry = dict_new();
+            dict_set(entry, "lib", path);
+            dict_set(entry, "name", fn_name_of(fn_src));
+            try {
+                h hash_dict = omc_canonical_hash(fn_src);
+                dict_set(entry, "canonical_hash", dict_get(hash_dict, "raw"));
+                dict_set(entry, "attractor", dict_get(hash_dict, "attractor"));
+            } catch e {
+                # Some fns use library-specific syntax that doesn't parse
+                # in isolation (e.g. closures referencing the module's
+                # imports). Skip the hash for these; the name + sig still
+                # serve as a discovery hint.
+                dict_set(entry, "canonical_hash", 0);
+                dict_set(entry, "attractor", 0);
+            }
+            dict_set(entry, "signature", signature_first_line(fn_src));
+            arr_push(manifest, entry);
+            j = j + 1;
+        }
+        i = i + 1;
+    }
+    return manifest;
+}
+
+fn main() {
+    h pack = omc_bootstrap_pack();
+    h manifest = build_lib_manifest();
+    h bundle = dict_new();
+    dict_set(bundle, "kind", "omc_onboarding_token_v1");
+    dict_set(bundle, "version", "2026.05.16");
+    dict_set(bundle, "bootstrap_pack", pack);
+    dict_set(bundle, "lib_manifest", manifest);
+    dict_set(bundle, "fn_count", arr_len(manifest));
+    dict_set(bundle, "bootstrap_bytes", str_len(pack));
+
+    # Substrate-sign the entire bundle so receivers can verify integrity.
+    h bundle_json = json_stringify(bundle);
+    h envelope = omc_msg_sign(bundle_json, 0, 7);  # sender=0, kind=7 (onboarding)
+    h envelope_json = omc_msg_serialize(envelope);
+
+    # Emit one JSON line: the substrate-signed envelope. The receiver
+    # verifies with omc_msg_verify and then json_parse the content.
+    print(envelope_json);
+}
+
+main();