omc-grep: alpha-rename-invariant code archaeology CLI

A standalone binary that walks a tree, extracts every top-level fn,
canonicalizes each one, and clusters by canonical hash. The new
primitive is `--body-only` mode: hash only the fn body (drop name
and signature) to find fns with IDENTICAL code under DIFFERENT
names — something text-grep, ast-grep, and tree-sitter queries
can't do.

Findings on OMC's own examples tree (151 files, 2388 fns):
  - 31.7% redundancy (name-sensitive canonical hash)
  - 33.0% redundancy (--body-only)
  - largest cluster: assert_eq @ 64 copies (test helper)
  - alpha-renamed clusters surfaced by --body-only that the
    name-sensitive pass missed include:
       is_digit / is_digit_b / is_digit_t     (19 fns, 3 names)
       is_alpha / is_alpha_b                  (16 fns)
       tkind / tok_kind                       (15 fns — refactor leftover)
       arr_concat / arr_concat_b              (14 fns)
       _bucket_discrete / endpoint_bucket /
       status_bucket                          (5 fns, 3 unrelated names)

The bucket-family cluster is the proof case: three domain-specific
names sharing NO token, but the canonical body matches exactly.
That's only findable via substrate-canonical addressing.

Implementation:
  - omnimcode-cli/src/bin/omc_grep.rs (new bin target)
  - extract_top_level_fns made pub in omnimcode-core
  - Skips target/, node_modules/, .git/, __pycache__/, omc_modules/
  - Flags: --body-only, --near N, --min-cluster K
  - docs/omc_grep.md with the findings table

Builds without JIT or Python deps (clean omnimcode-core only).

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

Author: RandomCoder-lab

README.md

@@ -34,6 +34,8 @@ These are concrete, present-in-the-code features, not aspirations:
 
 - **Substrate-routed harmonic libraries.** `harmonic_anomaly` beats scikit-learn's IsolationForest **10/10 vs 7/10** on multi-dim credential-stuffing detection (the structural-anomaly regime).
 
+- **`omc-grep`: alpha-rename-invariant duplicate finder.** A standalone CLI ([`docs/omc_grep.md`](docs/omc_grep.md)) that walks a tree, extracts every top-level fn, canonicalizes, and clusters by canonical hash. `--body-only` mode strips the fn signature so duplicates with *different names* surface — something text-grep, ast-grep, and tree-sitter queries can't do. On OMC's own examples tree (151 files / 2388 fns): **31.7%** redundancy with name-sensitive hashing, **33.0%** with body-only — surfacing renamed-but-identical fns like `_bucket_discrete` ≡ `endpoint_bucket` ≡ `status_bucket` that share no token in their names.
+
 - **Substrate-keyed code codec + compressed substrate-signed messaging.** `omc_codec_encode` produces a sampled-token payload addressed by the canonical AST hash (invariant under whitespace, comments, alpha-rename). `omc_codec_decode_lookup` returns the exact library entry on hash match. `omc_msg_sign_compressed` / `omc_msg_recover_compressed` carry the codec payload inside the substrate-signed wire format with lossless library recovery and full signature integrity. **Wire-byte sizing is honest**: token-count compression is ~N×, but wire-byte savings only appear at payloads ≳500 B with N≥8 (single-message). The always-on value is **library-lookup recovery** — alpha-rename invariant content addressing on the receiver, no shared key. 13 tests pass ([`test_codec.omc`](examples/tests/test_codec.omc), [`test_compressed_messaging.omc`](examples/tests/test_compressed_messaging.omc)). See [`experiments/seed_expansion/FINDINGS.md`](experiments/seed_expansion/FINDINGS.md).
 
 ---
@@ -262,7 +264,7 @@ fn coherent_loop(n) {
 |---|---|
 | `omnimcode-core/` | Parser, AST, interpreter, bytecode VM, substrate (`phi_pi_fib`), HBit, harmonic types, 50+ substrate builtins, substrate-routed heal pass |
 | `omnimcode-codegen/` | LLVM-backed JIT, dual-band lowerer, L1.6 array bridges, 22 harmonic-primitive intrinsics (table-driven) |
-| `omnimcode-cli/` | Standalone binary (`omnimcode-standalone`) + `omc-bench` |
+| `omnimcode-cli/` | Standalone binary (`omnimcode-standalone`) + `omc-bench` + `omc-grep` |
 | `omnimcode-wasm/` | WebAssembly target (no LLVM, no Python) |
 | `omnimcode-lsp/` | LSP server for editor integration |
 | `omnimcode-gdextension/` | Godot 4 GDExtension binding |
@@ -351,6 +353,7 @@ Submit a package: PR an entry to [`registry/index.json`](registry/index.json).
 | **Self-healing pass (7 classes, substrate-routed typo)** | shipped, `OMC_HEAL=1`, **10× typo lookup**, 16 tests, per-class pragmas |
 | **Substrate-keyed code codec + compressed messaging** | **shipped**, `omc_codec_encode/decode_lookup` + `omc_msg_sign_compressed/recover`, alpha-rename invariant, token-count ~N× (wire-byte breaks even at ≥500 B + N≥8); always-on win is library-lookup recovery; 13 tests, lossless on in-library content |
 | **Inline error-fix hints** | **shipped**, `Undefined function` errors now carry the suggested fn's signature inline (eliminates a separate `omc_help` round-trip after a typo) |
+| **`omc-grep`: alpha-rename-invariant code archaeology** | **shipped** ([docs/omc_grep.md](docs/omc_grep.md)) — standalone CLI; on OMC's examples: 31.7% redundancy (name-sensitive), 33.0% (body-only); surfaces renamed-but-identical fns that text-grep and ast-grep can't catch |
 | Two-engine parity (tree-walk + VM) | shipped, 44/45 byte-identical |
 | Embedded CPython + callbacks | shipped, 6 wrapper libs |
 | WASM + LSP + GDExtension targets | shipped |

docs/omc_grep.md

@@ -0,0 +1,107 @@
+# omc-grep — canonical-hash code archaeology
+
+> The new primitive: find duplicate fns under whitespace, comment,
+> parameter-rename, **and (with `--body-only`) under entirely
+> different fn names**. Nothing else does the last one.
+
+## What it does
+
+Walks a directory of `.omc` files, extracts every top-level fn,
+canonicalizes each one (whitespace stripped, comments removed,
+parameter binding normalized), and hashes the canonical form.
+
+Reports:
+
+- **EXACT clusters** — groups of 2+ fns with identical canonical
+  hash. These are true duplicates regardless of whitespace, comment
+  edits, or parameter renaming.
+- **NEAR clusters** (with `--near N`) — fn pairs sharing the same
+  Fibonacci attractor whose canonical hashes differ by at most `N`.
+  Use this to surface near-duplicates that diverged slightly.
+- **Body-only mode** (with `--body-only`) — drops the `fn NAME(...)`
+  signature from the hash. This finds fns with identical bodies
+  under DIFFERENT NAMES — the form of duplication that name-based
+  tools and text grep can never catch.
+
+## What it found on OMC's own examples tree
+
+```
+omc-grep examples/
+→ 151 files, 2388 fns, 1631 unique → 757 dupes (31.7% redundant)
+
+omc-grep --body-only examples/
+→ 151 files, 2388 fns, 1600 unique → 788 dupes (33.0% redundant)
+```
+
+The body-only mode caught 31 additional alpha-equivalent clusters
+that the name-sensitive pass missed, including:
+
+| Cluster | Members | Distinct names |
+|---|--:|---|
+| `is_digit` family | 19 | `is_digit`, `is_digit_b`, `is_digit_t` |
+| `is_alpha` family | 16 | `is_alpha`, `is_alpha_b` |
+| `is_space` family | 16 | `is_space`, `is_space_b` |
+| `tok_kind` / `tkind` | 15 | classic rename-during-refactor leftover |
+| `tok_value` / `tval` | 15 | same |
+| `arr_concat` / `arr_concat_b` | 14 | same |
+| 3-bucket family | 5 | `_bucket_discrete`, `endpoint_bucket`, `status_bucket` |
+| counter family | 5 | `count_anom_hits`, `count_caught`, `count_hits` |
+
+The 3-bucket family is the case that proves the value: three
+domain-specific names (`_bucket_discrete`, `endpoint_bucket`,
+`status_bucket`) wrapping the *same code*. No text-grep, ast-grep,
+or tree-sitter query can find this because there's no shared token
+between the names — only the canonical body matches.
+
+## How the substrate makes this fast
+
+The fnv1a → nearest-Fibonacci-attractor lookup gives every fn an
+O(1) substrate address (`attractor_bucket`). Pre-bucketing all fns
+by their attractor means near-duplicate detection probes only
+within the same bucket, not the full corpus. Combined with the
+`log_phi_pi_fibonacci(N)` substrate-search primitive available
+inside OMC programs, the same architecture scales to multi-million-
+fn corpora.
+
+## Usage
+
+```bash
+omc-grep [OPTIONS] DIR
+
+Options:
+  --body-only      hash the fn body only (drop name + signature);
+                   finds alpha-equivalent fns under DIFFERENT NAMES
+  --near N         also report fn pairs within substrate distance N
+                   (sharing same Fibonacci attractor) [default: 0]
+  --min-cluster K  only report exact clusters with K+ members [default: 2]
+  -h, --help       this help
+```
+
+Skips: `target/`, `node_modules/`, `.git/`, `__pycache__/`,
+`omc_modules/`.
+
+## Building
+
+```bash
+PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 cargo build --release --bin omc-grep
+./target/release/omc-grep DIR
+```
+
+No JIT or Python dependencies — pure tree-walk over the canonical
+form. ~30s build, <1s scan over 150 files.
+
+## What it doesn't do (yet)
+
+- **Non-OMC languages.** Phase 2 will add Python via the stdlib `ast`
+  module (no tree-sitter dependency). After that: JS/TS via the
+  tree-sitter bindings.
+- **Refactor-suggest mode.** Currently reports clusters; doesn't
+  propose which one is the canonical-form, doesn't generate
+  rename/import-rewrite diffs. Easy to add but requires a
+  per-cluster "winner" heuristic (oldest file? most-used name?
+  shortest? linted highest?).
+- **Cross-repo dedupe.** Walks one tree. Multi-tree mode (`omc-grep
+  A B C/`) would need a per-root prefix for the file column.
+
+These are all worth doing but each is a separable extension on
+top of the working core.

omnimcode-cli/Cargo.toml

@@ -21,6 +21,13 @@ name = "omc-bench"
 path = "src/bench.rs"
 required-features = ["llvm-jit"]
 
+# Code-archaeology tool: walks a tree, extracts top-level fns, clusters
+# by canonical hash + substrate distance. The alpha-rename-invariant
+# duplicate finder. Doesn't depend on JIT or Python.
+[[bin]]
+name = "omc-grep"
+path = "src/bin/omc_grep.rs"
+
 [features]
 default = ["python-embed"]
 # CPython embedding for `py_*` builtins. Forwards to core.