substrate codec + compressed messaging + inline error hints

Four new builtins make substrate-aware code compression a first-class
OMC primitive:

- omc_codec_encode(code, every_n)         — sampled-token + substrate
                                            metadata payload
- omc_codec_decode_lookup(codec, library) — exact recovery by
                                            canonical-hash match
- omc_msg_sign_compressed(content, sender, kind, every_n)
- omc_msg_recover_compressed(msg, library) — verify + library lookup

The codec is alpha-rename invariant (canonical-hash addressing) and
yields ~5–7x wire-payload reduction with lossless recovery for
in-library content. Substrate signatures preserved across compression.

Tested: 7 cases in test_codec.omc, 6 in test_compressed_messaging.omc.
All 13 pass. Existing test_introspection unaffected (13 pass).

Inline-error UX: Undefined-function error now carries the
suggested function's signature inline, so the LLM iteration loop
no longer needs a separate omc_help round-trip after a typo.

Empirical results from experiments/seed_expansion/ (PyTorch):
  - v3 structural-features 40/10 split: 0/10 held-out exact
  - v4 token-sampled (N=2, N=3): 0/10 held-out exact
  - Closed-set v2 still 100% exact — the substrate-keyed lookup is
    sound; open-set generalization needs scale.

See FINDINGS.md for full extrapolation of what shipped vs. what
remains data-budget bound.

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

Author: RandomCoder-lab

Cargo.lock

@@ -0,0 +1,48 @@
+# Tandem demo: REPLY side (Hermes responding to Claude).
+# Reads a substrate-signed message from Claude, verifies it,
+# then sends back a signed response with sender_id=28765 and kind=2.
+
+fn show(label, v) { print(concat_many(label, " = ", to_string(v))); }
+
+fn main() {
+    h HERMES_ID = 28765;
+    h KIND_RESPONSE = 2;
+
+    // Read the incoming wire from Claude
+    h wire = read_file("/home/thearchitect/omc_channel/from_claude.json");
+    h msg = omc_msg_deserialize(wire);
+    h check = omc_msg_verify(msg);
+
+    show("valid signature?  ", dict_get(check, "valid"));
+    show("sender_id         ", dict_get(check, "sender_id"));
+    show("kind              ", dict_get(check, "kind"));
+    show("expected_hash     ", dict_get(check, "expected_hash"));
+    show("actual_hash       ", dict_get(check, "actual_hash"));
+    show("drift_resonance   ", dict_get(check, "drift_resonance"));
+    show("drift_him         ", dict_get(check, "drift_him"));
+
+    if dict_get(check, "valid") == 1 {
+        print("");
+        print("=== Signature valid — content trustworthy ===");
+        h payload = dict_get(check, "content");   // extract verified content
+        print("Payload:");
+        print(payload);
+
+        // Now sign a response (we echo back the same payload for demo)
+        h resp_msg = omc_msg_sign(payload, HERMES_ID, KIND_RESPONSE);
+        show("resp packed ID    ", dict_get(resp_msg, "packed"));
+        show("resp content_hash ", dict_get(resp_msg, "content_hash"));
+        show("resp resonance    ", dict_get(resp_msg, "resonance"));
+        show("resp attractor    ", dict_get(resp_msg, "attractor"));
+
+        h resp_wire = omc_msg_serialize(resp_msg);
+        write_file("/home/thearchitect/omc_channel/from_hermes.json", resp_wire);
+        print("");
+        print("Wrote /home/thearchitect/omc_channel/from_hermes.json");
+        print("Hermes response sent (kind=2, sender_id=28765).");
+    } else {
+        print("");
+        print("=== SIGNATURE MISMATCH — will not respond ===");
+    }
+}
+main();

examples/demos/llm_tandem_reply.omc

@@ -0,0 +1,72 @@
+# Substrate-keyed codec — round-trip on a known library.
+
+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_encode_returns_required_fields() {
+    h codec = omc_codec_encode("fn f(x) { return x; }", 3);
+    assert_true(dict_has(codec, "sampled_tokens"), "has sampled_tokens");
+    assert_true(dict_has(codec, "content_hash"), "has content_hash");
+    assert_true(dict_has(codec, "attractor"), "has attractor");
+    assert_true(dict_has(codec, "dist"), "has dist");
+    assert_true(dict_has(codec, "original_tok_count"), "has original_tok_count");
+    assert_true(dict_has(codec, "compression_ratio"), "has compression_ratio");
+}
+
+fn test_compression_ratio_positive() {
+    h codec = omc_codec_encode("fn f(x) { return x; }", 3);
+    assert_true(dict_get(codec, "compression_ratio") > 1.0, "ratio > 1");
+}
+
+fn test_lookup_finds_known() {
+    h lib = [
+        "fn a() { return 1; }",
+        "fn b() { return 2; }",
+        "fn c() { return 3; }",
+    ];
+    h codec = omc_codec_encode(arr_get(lib, 1), 3);
+    h decoded = omc_codec_decode_lookup(codec, lib);
+    assert_eq(decoded, "fn b() { return 2; }", "library lookup");
+}
+
+fn test_lookup_misses_unknown() {
+    h lib = ["fn a() { return 1; }"];
+    h codec = omc_codec_encode("fn z() { return 99; }", 3);
+    h decoded = omc_codec_decode_lookup(codec, lib);
+    assert_true(decoded == null, "miss returns null");
+}
+
+fn test_alpha_equivalent_lookup_succeeds() {
+    # Canonical hash is invariant under rename, so encoding one
+    # alpha-equivalent form and looking up the other still hits.
+    h lib = ["fn f(x) { return x; }"];
+    h codec = omc_codec_encode("fn f(y) { return y; }", 3);
+    h decoded = omc_codec_decode_lookup(codec, lib);
+    assert_eq(decoded, "fn f(x) { return x; }", "alpha-rename lookup hits");
+}
+
+fn test_encode_n_2_keeps_more() {
+    # Same source, N=2 keeps roughly twice as many tokens as N=4.
+    h c2 = omc_codec_encode("fn add(x, y) { return x + y + 1; }", 2);
+    h c4 = omc_codec_encode("fn add(x, y) { return x + y + 1; }", 4);
+    h n2 = arr_len(dict_get(c2, "sampled_tokens"));
+    h n4 = arr_len(dict_get(c4, "sampled_tokens"));
+    assert_true(n2 > n4, "N=2 keeps more than N=4");
+}
+
+# Unknown-function error now includes signature hint inline.
+fn test_unknown_fn_inlines_signature_hint() {
+    h err = "";
+    try {
+        h _ = arr_softmx([1.0]);  # typo
+    } catch e {
+        err = e;
+    }
+    assert_true(re_match("did you mean", err) == 1, "did-you-mean present");
+    assert_true(re_match("signature", err) == 1, "inline signature hint present");
+}

examples/tests/test_codec.omc

@@ -0,0 +1,62 @@
+# Compressed substrate-signed messaging round-trip.
+
+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_compressed_sign_includes_codec() {
+    h msg = omc_msg_sign_compressed("fn f(x) { return x; }", 18173, 1, 3);
+    assert_true(dict_has(msg, "sampled_tokens"), "carries sampled_tokens");
+    assert_true(dict_has(msg, "content_hash"), "carries content_hash");
+    assert_true(dict_has(msg, "compression_ratio"), "has ratio");
+    assert_true(dict_get(msg, "compression_ratio") > 1.0, "compression > 1");
+}
+
+fn test_recover_in_library() {
+    h lib = [
+        "fn a() { return 1; }",
+        "fn b(x) { return x * 2; }",
+        "fn c(x, y) { return x + y; }",
+    ];
+    h msg = omc_msg_sign_compressed("fn b(x) { return x * 2; }", 18173, 1, 3);
+    h recovered = omc_msg_recover_compressed(msg, lib);
+    assert_eq(recovered, "fn b(x) { return x * 2; }", "recovered exact");
+}
+
+fn test_recover_alpha_equivalent() {
+    # Sender renames params; receiver's library has the original name.
+    h lib = ["fn b(x) { return x * 2; }"];
+    h msg = omc_msg_sign_compressed("fn b(y) { return y * 2; }", 18173, 1, 3);
+    h recovered = omc_msg_recover_compressed(msg, lib);
+    # Recovers the library version (canonical-hash invariant under rename).
+    assert_eq(recovered, "fn b(x) { return x * 2; }", "alpha-eq recovery");
+}
+
+fn test_recover_miss() {
+    h lib = ["fn a() { return 1; }"];
+    h msg = omc_msg_sign_compressed("fn nope() { return 99; }", 18173, 1, 3);
+    h recovered = omc_msg_recover_compressed(msg, lib);
+    assert_true(recovered == null, "miss → null");
+}
+
+fn test_substrate_metadata_present() {
+    h msg = omc_msg_sign_compressed("fn f() {}", 18173, 1, 3);
+    assert_true(dict_has(msg, "resonance"), "has resonance");
+    assert_true(dict_has(msg, "him_score"), "has him");
+    assert_true(dict_has(msg, "attractor"), "has attractor");
+    assert_true(dict_has(msg, "packed"), "has packed");
+}
+
+fn test_wire_serialize_roundtrip() {
+    # Sign compressed, serialize to wire, deserialize, recover via library.
+    h lib = ["fn add(x, y) { return x + y; }"];
+    h msg = omc_msg_sign_compressed("fn add(a, b) { return a + b; }", 18173, 1, 3);
+    h wire = omc_msg_serialize(msg);
+    h received = omc_msg_deserialize(wire);
+    h recovered = omc_msg_recover_compressed(received, lib);
+    assert_eq(recovered, "fn add(x, y) { return x + y; }", "wire roundtrip");
+}