Phase 3: codec ↔ package manager

Two new builtins make registry-installed packages a first-class codec
library:

- omc_registry_codec_library() -> string[]
    Scans omc_modules/ for *.omc files and returns every top-level
    fn definition as a separate string entry. Empty array if
    omc_modules/ doesn't exist (graceful no-op).
- omc_msg_recover_from_registry(msg: dict) -> string|null
    Convenience for omc_msg_recover_compressed(msg,
    omc_registry_codec_library()). Walks installed packages,
    returns the matching canonical source or null.

Brace-aware fn extractor (extract_top_level_fns) tracks # line
comments + "..."/'...' string literals so braces inside literals
don't throw off depth counting.

Demos:
- examples/demos/llm_tandem_registry.omc: writes a synthetic
  stats package to omc_modules/, signs an alpha-renamed copy of
  pkg_mean, recovers the original via registry. Verified end-to-end
  (3 fns extracted, canonical-hash match, returns library's
  parameter name 'vs' not sender's 'xs').
- examples/tests/test_codec_registry.omc: 3 tests covering the
  graceful-no-omc_modules path.

README + INDEX.md updated. 177 OMC tests total, all green.

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

Author: RandomCoder-lab

README.md

@@ -250,6 +250,8 @@ fn coherent_loop(n) {
 | [`examples/tests/test_heal_pass.omc`](examples/tests/test_heal_pass.omc) | 16 tests for the self-healing compiler's heal classes + per-class pragmas |
 | [`examples/tests/test_codec.omc`](examples/tests/test_codec.omc) | 7 tests for `omc_codec_encode/decode_lookup` — alpha-rename invariant library recovery + inline error-hint UX check |
 | [`examples/tests/test_compressed_messaging.omc`](examples/tests/test_compressed_messaging.omc) | 6 tests: substrate-signed wire payloads carrying codec output, alpha-equivalent recovery, JSON round-trip |
+| [`examples/tests/test_codec_registry.omc`](examples/tests/test_codec_registry.omc) | 3 tests: `omc_registry_codec_library` + `omc_msg_recover_from_registry` graceful no-op when omc_modules/ doesn't exist |
+| [`examples/demos/llm_tandem_registry.omc`](examples/demos/llm_tandem_registry.omc) | End-to-end: synthetic package in omc_modules/, signs renamed copy, recovers via registry — alpha-rename invariant |
 | [`experiments/seed_expansion/FINDINGS.md`](experiments/seed_expansion/FINDINGS.md) | Empirical writeup: substrate-keyed codec works (lossless on in-library content); open-set ML stays data-budget bound at 40 samples — honest |
 
 ---
@@ -269,7 +271,7 @@ fn coherent_loop(n) {
 | `experiments/substrate_primitives/` | Empirical comparison of substrate vs native vs OMC search |
 | `examples/lib/` | `substrate.omc`, `harmonic_anomaly`, `harmonic_clustering`, `harmonic_recommend`, np/pd/sklearn/torch/requests/sqlite |
 | `examples/datascience/` | Real-data demos with honest numbers |
-| `examples/tests/` | `test_substrate_primitives.omc` (57), `test_new_builtins.omc` (70), `test_harmonic_libs.omc` (18), `test_heal_pass.omc` (16), `test_codec.omc` (7), `test_compressed_messaging.omc` (6) — **174 total** |
+| `examples/tests/` | `test_substrate_primitives.omc` (57), `test_new_builtins.omc` (70), `test_harmonic_libs.omc` (18), `test_heal_pass.omc` (16), `test_codec.omc` (7), `test_compressed_messaging.omc` (6), `test_codec_registry.omc` (3) — **177 total** |
 | `docs/` | Substrate audit, JIT benchmarks, anomaly-detection comparisons |
 | `registry/` | Central package registry (sha256-verified) |
 

examples/demos/llm_tandem_registry.omc

@@ -0,0 +1,56 @@
+# Tandem demo: codec recovery via the installed registry library.
+#
+# Phase 3: instead of passing an explicit library array to
+# omc_msg_recover_compressed, the receiver calls
+# omc_msg_recover_from_registry(msg) — which automatically scans
+# omc_modules/ (the package-manager install directory) for matching
+# canonical-hash content.
+#
+# This demo:
+#   1. Synthesizes a tiny "stats" package and writes it to
+#      omc_modules/stats_pkg.omc.
+#   2. Signs an alpha-renamed copy of one of its functions.
+#   3. Recovers the original via omc_msg_recover_from_registry.
+#   4. Shows that the recovered source matches the package's
+#      canonical form, not the sender's renamed form.
+#
+# Run with:
+#   ./target/release/omnimcode-standalone examples/demos/llm_tandem_registry.omc
+
+fn show(label, v) { print(concat_many(label, " = ", to_string(v))); }
+
+fn main() {
+    # 1. Write a synthetic registry package.
+    h pkg = concat_many(
+        "# Synthetic stats package for demo purposes.\n",
+        "fn pkg_mean(vs) { h n = arr_len(vs); h s = 0.0; h i = 0; while i < n { s = s + arr_get(vs, i); i = i + 1; } return s / n; }\n",
+        "fn pkg_sum(vs) { h n = arr_len(vs); h s = 0.0; h i = 0; while i < n { s = s + arr_get(vs, i); i = i + 1; } return s; }\n",
+        "fn pkg_max(vs) { h n = arr_len(vs); h m = arr_get(vs, 0); h i = 1; while i < n { if arr_get(vs, i) > m { m = arr_get(vs, i); } i = i + 1; } return m; }\n"
+    );
+    write_file("omc_modules/stats_pkg.omc", pkg);
+    print("[setup] Wrote synthetic package to omc_modules/stats_pkg.omc");
+
+    # 2. Inspect what the registry library now contains.
+    h lib = omc_registry_codec_library();
+    show("registry library size", arr_len(lib));
+
+    # 3. Sender writes a RENAMED variant of pkg_mean (xs instead of vs).
+    h sender_src = "fn pkg_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_compressed(sender_src, 18173, 1, 3);
+    show("sender content_hash  ", dict_get(msg, "content_hash"));
+
+    # 4. Receiver recovers via registry (no explicit library passed).
+    h recovered = omc_msg_recover_from_registry(msg);
+    if recovered == null {
+        print("[FAIL] registry lookup MISSED — canonical hash not in any installed package");
+    } else {
+        print("[OK] registry lookup hit");
+        print("Recovered (registry's canonical form, with 'vs' parameter):");
+        print(recovered);
+        print("");
+        print("Sender used 'xs', registry entry uses 'vs'.");
+        print("Canonical hash matched because rename is invariant.");
+    }
+}
+
+main();

examples/tests/INDEX.md

@@ -1,6 +1,6 @@
 # Test suite index
 
-**65 test files, 997 `fn test_*` functions, all green under `omnimcode-standalone --test FILE`.**
+**66 test files, 1000 `fn test_*` functions, all green under `omnimcode-standalone --test FILE`.**
 
 This is a map of what's covered, organized by surface area — not an
 exhaustive doc. Run any file with `--test FILE` to see the actual
@@ -33,6 +33,7 @@ exercise many sub-assertions inside one `test_*` body, so the
 |---|--:|---|
 | `test_codec.omc` | 7 | `omc_codec_encode/decode_lookup` — alpha-rename invariant library recovery + inline error-hint UX check |
 | `test_compressed_messaging.omc` | 6 | `omc_msg_sign_compressed/recover` — substrate-signed wire payloads carrying codec output, JSON round-trip |
+| `test_codec_registry.omc` | 3 | `omc_registry_codec_library` / `omc_msg_recover_from_registry` — graceful no-op when omc_modules/ absent |
 | `test_substrate_messaging.omc` | 10 | The base substrate-signed messaging protocol (pre-codec) — `omc_msg_sign / verify / serialize` |
 | `test_canonical.omc` | 15 | AST canonicalization — the LLM-reach-for semantic-equivalence layer |
 | `test_canonical_extras.omc` | 11 | More canonical / structural-equivalence cases |

examples/tests/test_codec_registry.omc

@@ -0,0 +1,36 @@
+# Codec ↔ registry integration.
+#
+# These tests exercise omc_registry_codec_library and
+# omc_msg_recover_from_registry. They run in any working directory:
+# if omc_modules/ doesn't exist, the lookup gracefully returns
+# empty / null without erroring.
+
+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_registry_library_returns_array() {
+    h lib = omc_registry_codec_library();
+    assert_true(arr_len(lib) >= 0, "returns an array (possibly empty)");
+}
+
+fn test_recover_from_registry_handles_unknown() {
+    # If omc_modules/ doesn't exist or doesn't contain this fn, returns null.
+    h msg = omc_msg_sign_compressed("fn nonexistent_xyz_123() { return 42; }", 18173, 1, 3);
+    h r = omc_msg_recover_from_registry(msg);
+    assert_true(r == null, "unknown fn → null");
+}
+
+fn test_recover_from_registry_returns_null_or_string() {
+    h msg = omc_msg_sign_compressed("fn add(x, y) { return x + y; }", 18173, 1, 3);
+    h r = omc_msg_recover_from_registry(msg);
+    # Either null (not in registry) or a string (matched). No error.
+    h ok = false;
+    if r == null { ok = true; }
+    else { ok = str_len(r) > 0; }
+    assert_true(ok, "null or non-empty string");
+}

omnimcode-core/src/docs.rs

@@ -1137,6 +1137,20 @@ pub const BUILTINS: &[BuiltinDoc] = &[
         example: "omc_msg_recover_compressed(msg, shared_library)  // recovered source",
         unique_to_omc: true,
     },
+    BuiltinDoc {
+        name: "omc_registry_codec_library", category: "messaging",
+        signature: "() -> string[]",
+        description: "Scan omc_modules/ for installed registry packages and return every top-level fn definition as a separate string. Suitable as the library arg to omc_codec_decode_lookup / omc_msg_recover_compressed. Empty array if omc_modules/ doesn't exist.",
+        example: "omc_registry_codec_library()  // [\"fn mean(xs) {...}\", ...]",
+        unique_to_omc: true,
+    },
+    BuiltinDoc {
+        name: "omc_msg_recover_from_registry", category: "messaging",
+        signature: "(msg: dict) -> string|null",
+        description: "Convenience for omc_msg_recover_compressed(msg, omc_registry_codec_library()). Returns the matching registry-package fn source, or null if no installed package contains it.",
+        example: "omc_msg_recover_from_registry(msg)  // recovered registry-fn source or null",
+        unique_to_omc: true,
+    },
     BuiltinDoc {
         name: "omc_prompt_agent", category: "messaging",
         signature: "(target_id: int, prompt: string, sender_id: int, channel?: string) -> int",

omnimcode-core/src/interpreter.rs

@@ -8332,6 +8332,69 @@ impl Interpreter {
                 }
                 Ok(Value::Null)
             }
+            // omc_registry_codec_library() -> string[]
+            //   Scan omc_modules/ for installed registry packages, extract
+            //   each top-level fn definition as a separate string entry.
+            //   The returned array is suitable as the library argument to
+            //   omc_codec_decode_lookup / omc_msg_recover_compressed.
+            "omc_registry_codec_library" => {
+                let dir = std::path::Path::new("omc_modules");
+                if !dir.is_dir() {
+                    return Ok(Value::Array(HArray::from_vec(vec![])));
+                }
+                let mut entries: Vec<Value> = Vec::new();
+                if let Ok(rd) = std::fs::read_dir(dir) {
+                    for ent in rd.flatten() {
+                        let p = ent.path();
+                        if p.extension().and_then(|s| s.to_str()) != Some("omc") {
+                            continue;
+                        }
+                        if let Ok(src) = std::fs::read_to_string(&p) {
+                            for fn_src in extract_top_level_fns(&src) {
+                                entries.push(Value::String(fn_src));
+                            }
+                        }
+                    }
+                }
+                Ok(Value::Array(HArray::from_vec(entries)))
+            }
+            // omc_msg_recover_from_registry(msg) -> string|null
+            //   Convenience: omc_msg_recover_compressed(msg,
+            //   omc_registry_codec_library()). Returns the matching
+            //   library entry's canonical source, or null on miss.
+            "omc_msg_recover_from_registry" => {
+                if args.is_empty() {
+                    return Err("omc_msg_recover_from_registry requires (msg: dict)".to_string());
+                }
+                let v = self.eval_expr(&args[0])?;
+                let target_hash = if let Value::Dict(d) = v {
+                    d.borrow().get("content_hash").map(|x| x.to_int()).unwrap_or(0)
+                } else {
+                    return Err("omc_msg_recover_from_registry: msg must be a dict".to_string());
+                };
+                let dir = std::path::Path::new("omc_modules");
+                if !dir.is_dir() {
+                    return Ok(Value::Null);
+                }
+                if let Ok(rd) = std::fs::read_dir(dir) {
+                    for ent in rd.flatten() {
+                        let p = ent.path();
+                        if p.extension().and_then(|s| s.to_str()) != Some("omc") {
+                            continue;
+                        }
+                        if let Ok(src) = std::fs::read_to_string(&p) {
+                            for fn_src in extract_top_level_fns(&src) {
+                                let canon = crate::canonical::canonicalize(&fn_src)
+                                    .unwrap_or_else(|_| fn_src.clone());
+                                if crate::tokenizer::fnv1a_64(canon.as_bytes()) == target_hash {
+                                    return Ok(Value::String(fn_src));
+                                }
+                            }
+                        }
+                    }
+                }
+                Ok(Value::Null)
+            }
             "omc_find_similar" => {
                 // omc_find_similar(query, corpus[]) → [{index, distance}, ...]
                 // ranked closest-first by canonical-hash distance.
@@ -10607,6 +10670,74 @@ impl Interpreter {
 /// (arr_push, arr_set, dict_set, dict_del) is already handled by
 /// dedicated opcodes in the compiler, so it never reaches
 /// vm_call_builtin in the first place.
+/// Walk `src` and return every top-level `fn NAME(...) { ... }` as a
+/// separate string. Skips nested fns and `#`-prefixed line comments;
+/// tracks `"..."` and `'...'` so braces inside string literals don't
+/// throw off depth counting. Used by omc_registry_codec_library and
+/// omc_msg_recover_from_registry.
+fn extract_top_level_fns(src: &str) -> Vec<String> {
+    let bytes = src.as_bytes();
+    let n = bytes.len();
+    let mut out = Vec::new();
+    let mut i = 0usize;
+    while i < n {
+        // Skip line comments.
+        if bytes[i] == b'#' {
+            while i < n && bytes[i] != b'\n' { i += 1; }
+            continue;
+        }
+        // Skip string literals at top level.
+        if bytes[i] == b'"' || bytes[i] == b'\'' {
+            let q = bytes[i]; i += 1;
+            while i < n && bytes[i] != q {
+                if bytes[i] == b'\\' && i + 1 < n { i += 2; } else { i += 1; }
+            }
+            if i < n { i += 1; }
+            continue;
+        }
+        // Recognize `fn ` only at start-of-line or after whitespace.
+        let at_boundary = i == 0 || bytes[i - 1].is_ascii_whitespace();
+        if at_boundary && i + 3 < n && &bytes[i..i + 3] == b"fn " {
+            let fn_start = i;
+            // Find the opening `{` of the body.
+            let mut j = i;
+            while j < n && bytes[j] != b'{' { j += 1; }
+            if j >= n { break; }
+            // Track depth, respecting strings + line comments.
+            let mut depth = 0i32;
+            let mut k = j;
+            while k < n {
+                let c = bytes[k];
+                if c == b'#' {
+                    while k < n && bytes[k] != b'\n' { k += 1; }
+                    continue;
+                }
+                if c == b'"' || c == b'\'' {
+                    let q = c; k += 1;
+                    while k < n && bytes[k] != q {
+                        if bytes[k] == b'\\' && k + 1 < n { k += 2; } else { k += 1; }
+                    }
+                    if k < n { k += 1; }
+                    continue;
+                }
+                if c == b'{' { depth += 1; }
+                else if c == b'}' {
+                    depth -= 1;
+                    if depth == 0 { k += 1; break; }
+                }
+                k += 1;
+            }
+            if depth == 0 && k > fn_start {
+                out.push(src[fn_start..k].to_string());
+            }
+            i = k;
+            continue;
+        }
+        i += 1;
+    }
+    out
+}
+
 fn vm_fast_dispatch(name: &str, args: &[Value]) -> Option<Result<Value, String>> {
     match (name, args.len()) {
         // ---- string ops ----