LLM ↔ LLM substrate-signed messaging protocol

Four new builtins for two agents to exchange OMC code with
substrate-derived integrity verification, no shared secret:

  omc_msg_sign(content, sender_id, kind)  -> dict
  omc_msg_verify(msg)                     -> {valid, sender_id, ...,
                                              drift_resonance, drift_him}
  omc_msg_serialize(msg)                  -> JSON wire string
  omc_msg_deserialize(wire)               -> dict

The message dict carries HBit metadata (resonance, him_score,
attractor) derived from the canonical-hash of the content. Receiver
recomputes the metadata from content and checks it matches —
tampering invalidates deterministically. No keys.

Bonus property: canonical-hash is invariant under whitespace /
comments / alpha-rename, so when LLMs reformat each other's code
(which they do) the signature still validates. That's the whole
point — substrate as the integrity carrier, not byte-for-byte
sameness.

Tandem demo (Claude → Hermes via shared /home/thearchitect/omc_channel/):
  examples/demos/llm_tandem_send.omc        — Claude side
  examples/demos/llm_tandem_receive.omc     — Hermes side
  examples/demos/LLM_TANDEM_PROTOCOL.md     — protocol spec for Hermes

Sender ID convention (in the spec): Claude=18173, Hermes=28765.
Kind values: 1=request, 2=response, 3=question, 4=review, 5=handshake.

Tests: 10 cases — sign/verify roundtrip, content tamper detection,
hash tamper detection, whitespace-invariant signatures, alpha-rename-
invariant signatures, JSON wire roundtrip, packed-id distinguishes
senders, hash distinguishes content, no drift on fresh sign, empty
content signs valid.

Honest framing in the protocol doc: this gives integrity, not
authentication (any agent can pick any sender_id) and not
confidentiality (content is plaintext). For real auth, layer Ed25519.
But the alpha-equivalent-content-still-verifies property is genuinely
OMC-only — and uniquely useful between LLMs that won't format their
output the same way.

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

Author: RandomCoder-lab

OMC_REFERENCE.md

@@ -2,9 +2,9 @@
 
 Auto-generated from `omnimcode-core/src/docs.rs`. Run `omc --gen-docs > OMC_REFERENCE.md` to regenerate.
 
-**Total documented builtins**: 629
+**Total documented builtins**: 633
 
-**OMC-unique**: 64 (no direct Python/NumPy equivalent — these are why you reach for OMC over numpy)
+**OMC-unique**: 66 (no direct Python/NumPy equivalent — these are why you reach for OMC over numpy)
 
 ---
 
@@ -52,6 +52,7 @@ Other high-value calls: `omc_unique_builtins()` (the OMC-only surface), `omc_pyt
 - [introspection](#introspection) (30 builtins)
 - [tokenizer](#tokenizer) (17 builtins)
 - [code_intel](#code_intel) (17 builtins)
+- [messaging](#messaging) (4 builtins)
 - [llm_workflow](#llm_workflow) (7 builtins)
 - [math](#math) (82 builtins)
 - [dicts](#dicts) (31 builtins)
@@ -4986,6 +4987,50 @@ omc_find_similar(q, corpus)  // [{index, distance}] — index of any distance-0
 
 ---
 
+## messaging
+
+### `omc_msg_sign` 🔱 *OMC-unique*
+
+**Signature**: `(content: string, sender_id: int, kind: int) -> dict`
+
+Wrap content in a substrate-signed message: HBit metadata derived from the canonical-hash of content. Receiver verifies by recomputing — no shared secret needed.
+
+```omc
+omc_msg_sign("fn f(){}", 42, 1)  // {content, sender_id, kind, content_hash, resonance, him_score, attractor, packed}
+```
+
+### `omc_msg_verify` 🔱 *OMC-unique*
+
+**Signature**: `(msg: dict) -> dict`
+
+Recompute substrate metadata from msg's content and check it matches signed values. Returns {valid, sender_id, kind, content, expected_hash, actual_hash, drift_resonance, drift_him}.
+
+```omc
+omc_msg_verify(msg)  // {valid: 1, ...}
+```
+
+### `omc_msg_serialize`
+
+**Signature**: `(msg: dict) -> string`
+
+Convert a signed-message dict to JSON wire form. Use when writing to a shared file / pipe / socket.
+
+```omc
+omc_msg_serialize(msg)  // JSON string
+```
+
+### `omc_msg_deserialize`
+
+**Signature**: `(wire: string) -> dict`
+
+Inverse of omc_msg_serialize. Parse JSON wire form back to a dict for omc_msg_verify.
+
+```omc
+omc_msg_verify(omc_msg_deserialize(wire))
+```
+
+---
+
 ## llm_workflow
 
 ### `omc_cheatsheet`

examples/demos/LLM_TANDEM_PROTOCOL.md

@@ -0,0 +1,113 @@
+# LLM ↔ LLM Substrate-Signed Messaging Protocol
+
+A minimal wire format for two LLMs to exchange OMC code (or any text)
+with **substrate-derived integrity verification** — no shared secret.
+
+## Idea
+
+A signed message wraps content with HBit metadata computed from the
+canonical-hash of the content. On receipt, the verifier recomputes the
+metadata from the content and checks it matches. Because the metadata
+is *derived* from the content (not added externally), tampering with
+the content invalidates the signature deterministically. No keys.
+
+Bonus property: the canonical-hash is invariant under whitespace,
+comments, and alpha-rename. So `fn f(x) { return x; }` and
+`fn f(y) { return y; }` are equivalent under the protocol — useful
+when LLMs reformat each other's code.
+
+## Message dict
+
+```
+{
+  "content":      string,    // the payload
+  "sender_id":   int,        // recommended: fnv1a_hash("agent_name")
+  "kind":         int,        // 1=code request, 2=response, 3=question, etc.
+  "content_hash": int,        // fnv1a of CANONICAL(content)
+  "resonance":    float,      // HInt(content_hash).resonance — recomputable
+  "him_score":    float,      // HInt(content_hash).him_score  — recomputable
+  "attractor":    int,        // nearest Fibonacci to content_hash
+  "packed":       int         // CRT-pack(sender_id, kind, hash mod M)
+}
+```
+
+Wire format: JSON via `omc_msg_serialize(msg)` / `omc_msg_deserialize(wire)`.
+
+## Builtins
+
+| Builtin | Purpose |
+|---------|---------|
+| `omc_msg_sign(content, sender_id, kind)` | Produce signed dict |
+| `omc_msg_verify(msg)` | Returns `{valid, sender_id, kind, content, expected_hash, actual_hash, drift_resonance, drift_him}` |
+| `omc_msg_serialize(msg)` | dict → JSON wire string |
+| `omc_msg_deserialize(wire)` | JSON → dict |
+
+## Suggested sender IDs
+
+Use `fnv1a_hash("agent_name") & 0x7fffffff` to derive stable per-LLM
+IDs. Canonical assignments for this demo:
+
+| Agent | sender_id |
+|-------|-----------|
+| Claude  | 18173 |
+| Hermes  | 28765 |
+| Other   | pick any |
+
+## Suggested `kind` values
+
+| kind | meaning |
+|------|---------|
+| 1 | code request — "implement this" |
+| 2 | code response — "here's an implementation" |
+| 3 | question — "what does this do?" |
+| 4 | review — "here's my critique" |
+| 5 | handshake — protocol-negotiation |
+
+## End-to-end example
+
+**Channel**: `/home/thearchitect/omc_channel/` (shared filesystem).
+
+**Send** (Claude):
+```bash
+./target/release/omnimcode-standalone examples/demos/llm_tandem_send.omc
+```
+
+**Receive** (Hermes — should be able to run on a fresh OMC checkout):
+```bash
+./target/release/omnimcode-standalone examples/demos/llm_tandem_receive.omc
+```
+
+## What Hermes should look for
+
+1. **`valid == 1`** — the substrate signature recomputed correctly. Trust the content.
+2. **`actual_hash == expected_hash`** — bit-for-bit content integrity (after canonicalization).
+3. **`drift_resonance ≈ 0`** and **`drift_him ≈ 0`** — substrate metadata is consistent.
+4. **`sender_id`** — confirms who emitted the message.
+5. **`kind`** — what to do with it.
+
+## What this catches
+
+- Content tampering (someone edits the payload mid-flight): hash mismatch.
+- Random corruption (JSON gets truncated / mangled): parse fails, then hash mismatch.
+- Stale signatures (someone signs A, swaps in B): hash mismatch.
+- Format drift (Hermes vs Claude format differently): **does NOT cause failure**,
+  because canonicalization runs before hashing. Round-trip OMC code through
+  either formatter and the signature still validates. *This is the point.*
+
+## What this does NOT catch
+
+- Identity forgery: any agent can pick any `sender_id`. There's no key
+  binding. For real auth, layer Ed25519 on top.
+- Replay attacks: same message can be re-sent. Add a nonce field if needed.
+- Confidentiality: content is plaintext. Wrap in TLS or sign-then-encrypt.
+
+## Round-trip property the protocol relies on
+
+```
+omc_canonical_hash(s) == omc_canonical_hash(omc_code_canonical(s))
+```
+
+Both agents must canonicalize the same way — both run the same OMC
+version. Different OMC versions = different canonicalizers = signatures
+won't match across versions. Pin the OMC build at protocol-negotiation
+time (use `kind = 5`).

examples/demos/llm_tandem_receive.omc

@@ -0,0 +1,34 @@
+# Tandem demo: RECEIVE side (e.g. Hermes reading from Claude).
+#
+# Reads the substrate-signed message from the shared channel,
+# verifies the signature, extracts the payload, and prints whether
+# it can trust the content (substrate metadata recomputable from
+# canonical content — no shared key needed).
+
+fn show(label, v) { print(concat_many(label, " = ", to_string(v))); }
+
+fn main() {
+    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 ===");
+        print("Payload:");
+        print(dict_get(check, "content"));
+    } else {
+        print("");
+        print("=== SIGNATURE MISMATCH — content tampered or corrupted ===");
+    }
+}
+
+main();

examples/demos/llm_tandem_send.omc

@@ -0,0 +1,35 @@
+# Tandem demo: SEND side (Claude → Hermes).
+#
+# Wraps a piece of OMC code as a substrate-signed message, serializes
+# to JSON, writes to the shared channel directory. Hermes picks it up
+# via llm_tandem_receive.omc.
+#
+# Run with:
+#   ./target/release/omnimcode-standalone examples/demos/llm_tandem_send.omc
+#
+# Sender ID convention: hash of "claude" or "hermes" via fnv1a.
+# This run uses CLAUDE_ID = 18173. Hermes uses HERMES_ID = 28765.
+
+fn show(label, v) { print(concat_many(label, " = ", to_string(v))); }
+
+fn main() {
+    h CLAUDE_ID = 18173;
+    h KIND_REQUEST = 1;
+
+    h payload = "fn compute_mean(xs) { h n = arr_len(xs); h s = 0.0; h i = 0; while i < n { s = s + arr_get(xs, i); i = i + 1; } return s / n; }";
+
+    h msg = omc_msg_sign(payload, CLAUDE_ID, KIND_REQUEST);
+    show("packed ID         ", dict_get(msg, "packed"));
+    show("content_hash      ", dict_get(msg, "content_hash"));
+    show("resonance         ", dict_get(msg, "resonance"));
+    show("attractor         ", dict_get(msg, "attractor"));
+
+    h wire = omc_msg_serialize(msg);
+    write_file("/home/thearchitect/omc_channel/from_claude.json", wire);
+    print("");
+    print("Wrote /home/thearchitect/omc_channel/from_claude.json");
+    print("Sender: CLAUDE_ID=18173, kind=1 (request).");
+    print("Hermes can verify substrate-signature integrity without trust.");
+}
+
+main();

examples/tests/test_substrate_messaging.omc

@@ -0,0 +1,94 @@
+# Substrate-signed LLM ↔ LLM messaging.
+
+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); } }
+
+# Basic sign + verify round-trip
+fn test_sign_verify_roundtrip() {
+    h msg = omc_msg_sign("fn f(x) { return x; }", 42, 1);
+    h check = omc_msg_verify(msg);
+    assert_eq(dict_get(check, "valid"), 1, "signed message verifies");
+    assert_eq(dict_get(check, "sender_id"), 42, "sender preserved");
+    assert_eq(dict_get(check, "kind"), 1, "kind preserved");
+}
+
+# Tampered content fails verification
+fn test_tampered_content_fails() {
+    h msg = omc_msg_sign("fn original() { return 1; }", 7, 2);
+    # Tamper with content but keep stale signature.
+    dict_set(msg, "content", "fn tampered() { return 99; }");
+    h check = omc_msg_verify(msg);
+    assert_eq(dict_get(check, "valid"), 0, "tampered → invalid");
+}
+
+# Tampered hash fails verification
+fn test_tampered_hash_fails() {
+    h msg = omc_msg_sign("fn f() {}", 7, 1);
+    dict_set(msg, "content_hash", 12345);  # garbage
+    h check = omc_msg_verify(msg);
+    assert_eq(dict_get(check, "valid"), 0, "bad hash → invalid");
+}
+
+# Whitespace + alpha-rename are SIGNATURE-PRESERVING
+# (because content is canonicalized before hashing)
+fn test_whitespace_invariant_signature() {
+    h m1 = omc_msg_sign("fn f(x) { return x; }", 1, 1);
+    h m2 = omc_msg_sign("fn   f ( x ) {  return  x  ;  }", 1, 1);
+    assert_eq(dict_get(m1, "content_hash"), dict_get(m2, "content_hash"),
+        "whitespace doesn't change signature");
+}
+
+fn test_alpha_rename_invariant_signature() {
+    h m1 = omc_msg_sign("fn f(x) { return x; }", 1, 1);
+    h m2 = omc_msg_sign("fn f(y) { return y; }", 1, 1);
+    assert_eq(dict_get(m1, "content_hash"), dict_get(m2, "content_hash"),
+        "alpha-rename doesn't change signature");
+}
+
+# Serialize → wire → deserialize → verify
+fn test_wire_format_roundtrip() {
+    h msg = omc_msg_sign("fn add(x, y) { return x + y; }", 99, 3);
+    h wire = omc_msg_serialize(msg);
+    assert_true(str_len(wire) > 0, "wire is non-empty");
+    h received = omc_msg_deserialize(wire);
+    h check = omc_msg_verify(received);
+    assert_eq(dict_get(check, "valid"), 1, "wire-roundtrip valid");
+    assert_eq(dict_get(check, "sender_id"), 99, "sender preserved");
+}
+
+# Different senders produce different packed IDs
+fn test_packed_id_distinguishes_senders() {
+    h m1 = omc_msg_sign("fn f() {}", 1, 1);
+    h m2 = omc_msg_sign("fn f() {}", 2, 1);
+    assert_true(dict_get(m1, "packed") != dict_get(m2, "packed"),
+        "different senders → different packed");
+}
+
+# Different content produces different hashes
+fn test_different_content_different_hash() {
+    h m1 = omc_msg_sign("fn f() { return 1; }", 1, 1);
+    h m2 = omc_msg_sign("fn f() { return 2; }", 1, 1);
+    assert_true(dict_get(m1, "content_hash") != dict_get(m2, "content_hash"),
+        "different content → different hash");
+}
+
+# Substrate metadata is recomputable (the verification check)
+fn test_substrate_metadata_recomputable() {
+    h msg = omc_msg_sign("hello", 1, 1);
+    h check = omc_msg_verify(msg);
+    # drift_resonance should be near 0 since we just signed it.
+    assert_true(dict_get(check, "drift_resonance") < 0.0001,
+        "no resonance drift on fresh sign");
+}
+
+# Empty content still produces a valid signed message
+fn test_empty_content_signs() {
+    h msg = omc_msg_sign("", 0, 0);
+    h check = omc_msg_verify(msg);
+    assert_eq(dict_get(check, "valid"), 1, "empty signs valid");
+}

omnimcode-core/src/compiler.rs

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

omnimcode-core/src/docs.rs

@@ -1080,6 +1080,35 @@ pub const BUILTINS: &[BuiltinDoc] = &[
         example: "omc_find_similar(q, corpus)  // [{index, distance}] — index of any distance-0 hit is the alpha-equiv match",
         unique_to_omc: true,
     },
+    // ---- Substrate-signed messaging (LLM ↔ LLM protocol) ----
+    BuiltinDoc {
+        name: "omc_msg_sign", category: "messaging",
+        signature: "(content: string, sender_id: int, kind: int) -> dict",
+        description: "Wrap content in a substrate-signed message: HBit metadata derived from the canonical-hash of content. Receiver verifies by recomputing — no shared secret needed.",
+        example: "omc_msg_sign(\"fn f(){}\", 42, 1)  // {content, sender_id, kind, content_hash, resonance, him_score, attractor, packed}",
+        unique_to_omc: true,
+    },
+    BuiltinDoc {
+        name: "omc_msg_verify", category: "messaging",
+        signature: "(msg: dict) -> dict",
+        description: "Recompute substrate metadata from msg's content and check it matches signed values. Returns {valid, sender_id, kind, content, expected_hash, actual_hash, drift_resonance, drift_him}.",
+        example: "omc_msg_verify(msg)  // {valid: 1, ...}",
+        unique_to_omc: true,
+    },
+    BuiltinDoc {
+        name: "omc_msg_serialize", category: "messaging",
+        signature: "(msg: dict) -> string",
+        description: "Convert a signed-message dict to JSON wire form. Use when writing to a shared file / pipe / socket.",
+        example: "omc_msg_serialize(msg)  // JSON string",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_msg_deserialize", category: "messaging",
+        signature: "(wire: string) -> dict",
+        description: "Inverse of omc_msg_serialize. Parse JSON wire form back to a dict for omc_msg_verify.",
+        example: "omc_msg_verify(omc_msg_deserialize(wire))",
+        unique_to_omc: false,
+    },
     // ---- LLM workflow bundles ----
     BuiltinDoc {
         name: "omc_cheatsheet", category: "llm_workflow",