@eyeauras/insight-cli 0.3.2 → 0.4.1

package/references/native/InsightCodeReferences.java

@@ -0,0 +1,129 @@
+import ghidra.app.script.GhidraScript;
+import ghidra.app.util.PseudoDisassembler;
+import ghidra.app.util.PseudoInstruction;
+import ghidra.program.model.address.*;
+import ghidra.program.model.mem.MemoryBlock;
+import com.google.gson.*;
+import java.nio.charset.StandardCharsets;
+import java.util.*;
+
+/** Bounded candidate discovery only. Never creates instructions, functions or references. */
+public class InsightCodeReferences extends GhidraScript {
+  static final String ALGORITHM="x86-64-code-reference-candidates-v1";
+  static final List<String> FORMS=List.of("call-rel32","lea-rip","mov-rip","call-rip-slot");
+  JsonObject p; long deadline,started; int bytesRead,tested,visited,maxBytes,maxCandidates,limit;
+  String reason="exhausted"; Address next; Set<Address> targets=new HashSet<>(); List<String> forms=new ArrayList<>();
+  List<Object> matches=new ArrayList<>();
+  Map<String,Object> map(Object... pairs){Map<String,Object> m=new LinkedHashMap<>();for(int i=0;i<pairs.length;i+=2)m.put((String)pairs[i],pairs[i+1]);return m;}
+  int number(String k,int d,int min,int max){int v=p.has(k)?p.get(k).getAsInt():d;if(v<min||v>max)throw new IllegalArgumentException(k+" outside supported bounds");return v;}
+  Address address(String s){if(!s.matches("[a-fA-F0-9]{1,16}"))throw new IllegalArgumentException("Default-space 64-bit hexadecimal address required");return currentProgram.getAddressFactory().getDefaultAddressSpace().getAddress(Long.parseUnsignedLong(s,16));}
+  String hex(Address a){return Long.toUnsignedString(a.getOffset(),16);}
+  boolean expired()throws Exception{monitor.checkCancelled();return System.nanoTime()>=deadline;}
+  record Encoding(String form,int length,int operand,int bits,int delta,String role){}
+  Encoding encoding(byte[] b,int start){
+    int i=start,rex=0;boolean word=false;
+    while(i<b.length&&i-start<15){int v=b[i]&255;if(v==0x66||v==0x26||v==0x2e||v==0x36||v==0x3e){word|=v==0x66;rex=0;i++;}else if(v>=0x40&&v<=0x4f){rex=v;i++;}else break;}
+    if(i>=b.length)return null;int op=b[i]&255,length,disp,operand,bits;String form,role;
+    if(op==0xe8){form="call-rel32";role="direct-call-target";length=i-start+5;disp=i+1;operand=0;bits=64;}
+    else{
+      if(i+1>=b.length)return null;int m=b[i+1]&255;if((m&0xc7)!=5)return null;
+      if(op==0x8d){form="lea-rip";operand=1;}
+      else if(op==0x88||op==0x89||op==0x8a||op==0x8b){form="mov-rip";operand=op==0x88||op==0x89?0:1;}
+      else if(op==0xff&&((m>>3)&7)==2){form="call-rip-slot";operand=0;}
+      else return null;
+      role=form.equals("call-rip-slot")?"pointer-slot":"effective-address";
+      length=i-start+6;disp=i+2;bits=form.equals("call-rip-slot")?64:op==0x88||op==0x8a?8:(rex&8)!=0?64:word?16:32;
+    }
+    if(length>15||start+length>b.length)return null;
+    int delta=(b[disp]&255)|((b[disp+1]&255)<<8)|((b[disp+2]&255)<<16)|(b[disp+3]<<24);
+    return new Encoding(form,length,operand,bits,delta,role);
+  }
+  boolean compatible(PseudoInstruction i,Encoding e,Address target){
+    if(i==null||i.getLength()!=e.length)return false;
+    if(e.form.equals("call-rel32"))return i.getMnemonicString().equalsIgnoreCase("CALL")&&i.getFlowType().isCall()&&!i.getFlowType().isComputed()&&Arrays.asList(i.getFlows()).contains(target);
+    if(e.form.equals("call-rip-slot"))return i.getMnemonicString().equalsIgnoreCase("CALL")&&i.getFlowType().isCall()&&i.getFlowType().isComputed();
+    if(!i.getMnemonicString().equalsIgnoreCase(e.form.equals("lea-rip")?"LEA":"MOV"))return false;
+    var register=i.getRegister(e.operand==0?1:0);return register!=null&&register.getBitLength()==e.bits;
+  }
+  String boundary(Address at,PseudoInstruction decoded,byte[] bytes)throws Exception{
+    var listing=currentProgram.getListing();var stored=listing.getInstructionContaining(at);
+    if(stored==null){var after=listing.getInstructionAfter(at);return after!=null&&after.getAddress().compareTo(at.addNoWrap(bytes.length-1))<=0?"listing-conflict":"unconfirmed";}
+    if(!stored.getAddress().equals(at)||stored.getLength()!=decoded.getLength()||!Arrays.equals(stored.getBytes(),bytes)||!stored.getMnemonicString().equals(decoded.getMnemonicString())||stored.getNumOperands()!=decoded.getNumOperands())return "listing-conflict";
+    for(int i=0;i<stored.getNumOperands();i++)if(!stored.getDefaultOperandRepresentation(i).equals(decoded.getDefaultOperandRepresentation(i)))return "listing-conflict";
+    return "listing-confirmed";
+  }
+  Object scan()throws Exception{
+    if(!currentProgram.getLanguageID().toString().startsWith("x86:LE:64:")||currentProgram.getAddressFactory().getDefaultAddressSpace().getSize()!=64)throw new UnsupportedOperationException("Code references V1 requires x86-64 little-endian default memory space");
+    var mode=currentProgram.getRegister("longMode");if(mode==null)throw new UnsupportedOperationException("64-bit decode mode is unavailable");
+    Address from=address(p.get("scan_from").getAsString()),through=address(p.get("scan_through").getAsString());if(from.compareTo(through)>0)throw new IllegalArgumentException("Inverted scan range");
+    var ts=p.getAsJsonArray("targets");if(ts.size()<1||ts.size()>64)throw new IllegalArgumentException("Select 1..64 targets");for(var t:ts)if(!targets.add(address(t.getAsString())))throw new IllegalArgumentException("Duplicate target");
+    var fs=p.getAsJsonArray("forms");for(String f:FORMS)for(var v:fs)if(f.equals(v.getAsString()))forms.add(f);if(forms.isEmpty()||new HashSet<>(forms).size()!=fs.size()||forms.size()!=fs.size())throw new IllegalArgumentException("Unsupported or duplicate form");
+    maxBytes=number("max_bytes",4194304,15,16777216);maxCandidates=number("max_candidates",200000,1,1000000);limit=number("limit",100,1,1000);
+    started=System.nanoTime();deadline=started+number("timeout_seconds",5,1,30)*1000000000L;
+    List<Address[]> runs=new ArrayList<>();var blocks=currentProgram.getMemory().getBlocks();Arrays.sort(blocks,Comparator.comparing(MemoryBlock::getStart));
+    for(var block:blocks){
+      if(expired()){reason="timeout";next=from;return result(from,through);}
+      if(!block.isInitialized()||!block.isExecute()||!block.getStart().getAddressSpace().equals(from.getAddressSpace())||block.getEnd().compareTo(from)<0||block.getStart().compareTo(through)>0)continue;
+      Address a=block.getStart().compareTo(from)<0?from:block.getStart(),z=block.getEnd().compareTo(through)>0?through:block.getEnd();
+      if(!runs.isEmpty()&&a.equals(runs.getLast()[1].next()))runs.getLast()[1]=z;
+      else runs.add(new Address[]{a,z});
+    }
+    var decoder=new PseudoDisassembler(currentProgram);
+    outer:for(int runIndex=0;runIndex<runs.size();runIndex++){
+      var run=runs.get(runIndex);Address at=run[0];
+      while(at.compareTo(run[1])<=0){
+        next=at;
+        if(expired()){reason="timeout";break outer;}
+        int remaining=maxBytes-bytesRead;long available=run[1].subtract(at)+1;
+        if(remaining<Math.min(15,available)){reason="byte_limit";break outer;}
+        int count=(int)Math.min(Math.min(65550,available),remaining);byte[] data=new byte[count];
+        if(currentProgram.getMemory().getBytes(at,data)!=count)throw new IllegalStateException("Incomplete initialized executable memory read");bytesRead+=count;
+        int positions=count==available?count:count-14;
+        for(int i=0;i<positions;i++){
+          Address here=at.addNoWrap(i);next=here;
+          if(expired()){reason="timeout";break outer;}
+          Encoding e=encoding(data,i);
+          if(e!=null&&forms.contains(e.form)){
+            if(visited==maxCandidates){reason="candidate_limit";break outer;}
+            var modeValue=currentProgram.getProgramContext().getValue(mode,here,false);
+            if(modeValue==null||!modeValue.equals(java.math.BigInteger.ONE))throw new UnsupportedOperationException("Candidate encountered outside known 64-bit decode mode");
+            visited++;
+            Address target=here.addWrap(e.length+(long)e.delta);
+            if(targets.contains(target)){
+              PseudoInstruction instruction=null;
+              try{instruction=decoder.disassemble(here,Arrays.copyOfRange(data,i,Math.min(data.length,i+15)));}
+              catch(ghidra.program.model.lang.InsufficientBytesException|ghidra.program.model.lang.UnknownInstructionException ignored){}
+              catch(ghidra.program.model.lang.UnknownContextException error){throw new UnsupportedOperationException("Native decoder context unavailable");}
+              if(compatible(instruction,e,target)){
+                byte[] bytes=Arrays.copyOfRange(data,i,i+e.length);String display=instruction.toString();
+                matches.add(map("from",hex(here),"to",hex(target),"form",e.form,"bytes",HexFormat.of().formatHex(bytes),"length",e.length,"operand_index",e.operand,"operand_bits",e.bits,"target_role",e.role,"validation","decoded","boundary",boundary(here,instruction,bytes),"instruction",display.substring(0,Math.min(512,display.length()))));
+              }
+            }
+          }
+          tested++;
+          if(here.equals(through)||here.equals(run[1])&&runIndex==runs.size()-1)next=null;
+          else next=here.addNoWrap(1);
+          if(matches.size()==limit&&next!=null){reason="result_limit";break outer;}
+        }
+        if(positions==available)break;
+        at=at.addNoWrap(positions);
+      }
+    }
+    if(reason.equals("exhausted"))next=null;
+    return result(from,through);
+  }
+  Object result(Address from,Address through){return map("algorithm",ALGORITHM,"language",currentProgram.getLanguageID().toString(),"forms",forms,"matches",matches,
+    "scan",map("from",hex(from),"through",hex(through),"next_start",next==null?null:hex(next),"complete",reason.equals("exhausted"),"reason",reason,"bytes_read",bytesRead,"tested_starts",tested,"visited_candidates",visited,"elapsed_ms",(System.nanoTime()-started)/1000000.0),
+    "coverage","Every byte start in initialized executable default-space memory, in address order; adjacent eligible blocks merge. Instructions fit entirely within the requested range. Overlapping decodes are separate candidates.",
+    "limitations",List.of("Decoded byte candidates do not prove instruction boundaries, execution or callgraph membership.","Indirect CALL targets identify pointer slots; pointees are never followed.","Only explicit V1 encodings; 67, FS/GS, LOCK/REP, SIMD and immediate MOV encodings are excluded at that start. A later start inside their bytes may still be a candidate."));}
+  public void run()throws Exception{
+    Map<String,Object> output;long modification=currentProgram.getModificationNumber();
+    try{
+      var request=JsonParser.parseString(new String(Base64.getDecoder().decode(getScriptArgs()[0]),StandardCharsets.UTF_8)).getAsJsonObject();
+      if(!request.get("operation").getAsString().equals("/code_references"))throw new IllegalArgumentException("Unknown code-reference operation");p=request.getAsJsonObject("parameters");
+      var value=(Map<String,Object>)scan();if(currentProgram.getModificationNumber()!=modification)throw new IllegalStateException("Read-only scan changed program modification counter");
+      value.put("read_only",map("modification_unchanged",true,"modification",Long.toString(modification)));output=map("value",value);
+    }catch(Exception error){output=map("error",map("code",error instanceof UnsupportedOperationException?"unsupported":error instanceof IllegalArgumentException?"invalid":"partial","message",Objects.toString(error.getMessage(),"Native code-reference scan failed")));}
+    println("INSIGHT_QUERY:"+new GsonBuilder().serializeNulls().create().toJson(output));
+  }
+}

package/references/native/InsightFunctionBoundaries.java

@@ -0,0 +1,56 @@
+package com.eyeauras.insight;
+
+import com.xebyte.core.*;
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import ghidra.program.model.listing.Program;
+import java.math.BigInteger;
+import java.util.*;
+
+/** Authenticated bounded runtime-region evidence for explicitly selected open programs. */
+public final class InsightFunctionBoundaries {
+  private static final Gson JSON=new GsonBuilder().disableHtmlEscaping().serializeNulls().create();
+  private final ProgramProvider programs;private final ThreadingStrategy threading;
+  public InsightFunctionBoundaries(ProgramProvider programs,ThreadingStrategy threading){this.programs=programs;this.threading=threading;}
+  @McpTool(path="/insight/function-boundaries/v1",method="GET",description="Compare recorded function membership with current mapped PE32+ AMD64 runtime regions; no semantic reconstruction",access=ToolAccess.READ_ONLY)
+  public Response boundaries(@Param(value="program",source=ParamSource.QUERY,allowEmpty=false) String path,
+      @Param(value="addresses",source=ParamSource.QUERY,allowEmpty=false) String addresses,
+      @Param(value="max_unwind_bytes",source=ParamSource.QUERY,allowEmpty=false) int maximum)throws Exception {
+    if(maximum<1||maximum>16777216||addresses==null||addresses.length()>339)throw new IllegalArgumentException("Expected 1–20 addresses and byte budget 1–16777216");
+    String[] words=addresses.split(",",-1);if(words.length<1||words.length>20)throw new IllegalArgumentException("Expected 1–20 addresses");
+    Set<String> unique=new HashSet<>();for(String word:words)if(!word.matches("0|[1-9a-f][a-f0-9]{0,15}")||!unique.add(word))throw new IllegalArgumentException("Expected distinct canonical addresses");
+    return threading.executeRead(()->{
+      if(programs==null||path==null||!path.startsWith("/")||path.length()>4096)throw new IllegalArgumentException("Explicit open program path required");
+      Program program=null;for(Program p:programs.getAllOpenPrograms())if(p!=null&&!p.isClosed()&&p.getDomainFile()!=null&&path.equals(p.getDomainFile().getPathname())){if(program!=null&&program!=p)throw new IllegalStateException("Ambiguous program path");program=p;}
+      if(program==null)throw new IllegalArgumentException("Program is not open");
+      var space=program.getAddressFactory().getDefaultAddressSpace();var memory=program.getMemory();var functions=program.getFunctionManager();long modification=program.getModificationNumber();
+      long lookupStarted=System.nanoTime();List<InsightPeRanges.Span> spans=new ArrayList<>();
+      for(var block:memory.getBlocks())if(block.isInitialized()&&block.getStart().getAddressSpace().equals(space))spans.add(new InsightPeRanges.Span(new BigInteger(Long.toUnsignedString(block.getStart().getOffset(),16),16),new BigInteger(Long.toUnsignedString(block.getEnd().getOffset(),16),16).add(BigInteger.ONE),block.isExecute()));
+      InsightPeRanges.Result scan;
+      if(space.getSize()!=64||space.getAddressableUnitSize()!=1||!program.getLanguageID().toString().equals("x86:LE:64:default"))scan=new InsightPeRanges.Result(Map.of("state","unavailable","complete",false,"reason","unsupported_language","headersSource","current-mapped-memory","recordCount",0,"recordsValidated",0,"bytesRead",0,"maximumBytes",maximum,"deadlineMilliseconds",5000),List.of());
+      else scan=new InsightPeRanges(new BigInteger(Long.toUnsignedString(program.getImageBase().getOffset(),16),16),spans,(at,out)->memory.getBytes(space.getAddress(at.longValue()),out),maximum,System::nanoTime,Arrays.stream(words).map(w->new BigInteger(w,16)).toList(),lookupStarted).run();
+      Map<String,Object> items=new LinkedHashMap<>();boolean complete=Boolean.TRUE.equals(scan.lookup().get("complete"));
+      for(String word:words){
+        BigInteger query=new BigInteger(word,16);Map<String,Object> row=new LinkedHashMap<>();Map<String,Object> database=null;
+        if(query.bitLength()<=space.getSize()){
+          var at=space.getAddress(query.longValue());var f=functions.getFunctionAt(at);String kind="exact-entry";if(f==null){f=functions.getFunctionContaining(at);kind="recorded-containing";}
+          if(f!=null)database=Map.of("entryPoint",Long.toUnsignedString(f.getEntryPoint().getOffset(),16),"kind",kind,"recordedBodyContainsAddress",f.getBody().contains(at));
+        }
+        row.put("database",database);InsightPeRanges.Range range=null;
+        for(var candidate:scan.ranges())if(query.compareTo(candidate.begin())>=0&&query.compareTo(candidate.endExclusive())<0){range=candidate;break;}
+        row.put("boundary",range==null?null:range.facts());row.put("status","unresolved");
+        if(!complete)row.put("reason","boundary_lookup_"+scan.lookup().get("state"));
+        else if(range!=null&&database!=null&&!database.get("entryPoint").equals(range.begin().toString(16)))row.put("reason","boundary_conflict");
+        else if(range!=null){
+          String entry=range.begin().toString(16);
+          if(functions.getFunctionAt(space.getAddress(range.begin().longValue()))==null)row.put("reason","runtime_entry_not_defined");
+          else{row.put("status","resolved");row.put("entryPoint",entry);row.put("kind","pe-runtime-range");row.put("recordedBodyContainsAddress",database!=null&&Boolean.TRUE.equals(database.get("recordedBodyContainsAddress")));}
+        }else if(database!=null){row.put("status","resolved");row.put("entryPoint",database.get("entryPoint"));row.put("kind",database.get("kind"));row.put("recordedBodyContainsAddress",database.get("recordedBodyContainsAddress"));}
+        else row.put("reason","no_runtime_range_or_recorded_function");
+        items.put(word,row);
+      }
+      if(modification!=program.getModificationNumber())throw new IllegalStateException("Program changed during function-boundary lookup");
+      return Response.text(JSON.toJson(Map.of("protocol","insight-function-boundaries-v1","modification",Long.toString(modification),"boundaryLookup",scan.lookup(),"items",items)));
+    });
+  }
+}

package/references/native/InsightInlineExecutor.java

@@ -0,0 +1,143 @@
+package insight;
+
+import com.google.gson.*;
+import generic.jar.ResourceFile;
+import ghidra.app.script.*;
+import ghidra.util.task.TaskMonitor;
+import java.io.*;
+import java.lang.reflect.*;
+import java.net.*;
+import java.nio.charset.StandardCharsets;
+import java.nio.channels.FileChannel;
+import java.nio.file.*;
+import java.security.MessageDigest;
+import java.util.*;
+import java.util.regex.*;
+import javax.tools.*;
+
+/** Owned Java-only inline executor. Never infers non-execution from exception text or stdout. */
+public final class InsightInlineExecutor {
+    static final int OUTPUT_BYTES=32768, MAX_DIAGNOSTICS=100;
+    static final Gson JSON=new GsonBuilder().serializeNulls().create();
+    static final class BoundedOutput extends OutputStream {
+        final ByteArrayOutputStream bytes=new ByteArrayOutputStream(); boolean truncated;
+        public synchronized void write(int b){if(bytes.size()<OUTPUT_BYTES)bytes.write(b);else truncated=true;}
+        public synchronized void write(byte[] b,int start,int length){int n=Math.min(length,OUTPUT_BYTES-bytes.size());bytes.write(b,start,n);if(n<length)truncated=true;}
+        synchronized String text(){return bytes.toString(StandardCharsets.UTF_8);}
+        synchronized Map<String,Object> value(){return Map.of("text",text(),"truncated",truncated,"maximumBytes",OUTPUT_BYTES);}
+    }
+    record Source(String name,String text,int prefixLines,int userLines,boolean wrapped) {}
+    /** Keep offsets/newlines, but hide comments and literals from declaration/import recognition. */
+    static String lexical(String s){
+        char[] out=s.toCharArray();int state=0;
+        for(int i=0;i<s.length();i++){
+            char c=s.charAt(i),n=i+1<s.length()?s.charAt(i+1):0;
+            if(state==0){
+                if(c=='/'&&n=='/'){out[i]=out[++i]=' ';state=1;}
+                else if(c=='/'&&n=='*'){out[i]=out[++i]=' ';state=2;}
+                else if(c=='"'&&i+2<s.length()&&s.startsWith("\"\"\"",i)){out[i]=out[i+1]=out[i+2]=' ';i+=2;state=5;}
+                else if(c=='"'||c=='\''){out[i]=' ';state=c=='"'?3:4;}
+            }else{
+                if(c!='\n'&&c!='\r')out[i]=' ';
+                if(state==1&&c=='\n')state=0;
+                else if(state==2&&c=='*'&&n=='/'){out[++i]=' ';state=0;}
+                else if((state==3||state==4)&&c=='\\'&&i+1<s.length()){if(s.charAt(i+1)!='\n')out[++i]=' ';}
+                else if((state==3&&c=='"')||(state==4&&c=='\''))state=0;
+                else if(state==5&&s.startsWith("\"\"\"",i)){out[i]=out[i+1]=out[i+2]=' ';i+=2;state=0;}
+            }
+        }
+        return new String(out);
+    }
+    static Source source(String code,String attempt){
+        String lex=lexical(code);
+        Matcher type=Pattern.compile("\\bpublic\\s+(?:(?:abstract|final|strictfp|sealed|non-sealed)\\s+)*(?:class|interface|enum|record)\\s+([A-Za-z_$][\\w$]*)").matcher(lex);
+        if(type.find()){
+            Matcher pkg=Pattern.compile("\\bpackage\\s+([A-Za-z_$][\\w$]*(?:\\s*\\.\\s*[A-Za-z_$][\\w$]*)*)\\s*;").matcher(lex);
+            String prefix=pkg.find()?pkg.group(1).replaceAll("\\s","")+".":"";
+            return new Source(prefix+type.group(1),code,0,code.split("\n",-1).length,false);
+        }
+        StringBuilder imports=new StringBuilder("import ghidra.app.script.GhidraScript;\n");char[] body=code.toCharArray();int lines=1;
+        Matcher im=Pattern.compile("(?m)^\\h*import\\s+(?:static\\s+)?[\\w.$*]+\\s*;").matcher(lex);
+        while(im.find()){
+            imports.append(code,im.start(),im.end()).append('\n');lines++;
+            for(int i=im.start();i<im.end();i++)if(body[i]!='\n'&&body[i]!='\r')body[i]=' ';
+        }
+        String name="InsightUser_"+attempt.replace("-","");
+        return new Source(name,imports+"public class "+name+" extends GhidraScript {\npublic void run() throws Exception {\n"+new String(body)+"\n}\n}\n",lines+2,code.split("\n",-1).length,true);
+    }
+    static String sha(String s)throws Exception{return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(s.getBytes(StandardCharsets.UTF_8)));}
+    static Map<String,Object> execution(String stage,boolean mayRun,Object invoked){
+        Map<String,Object> m=new LinkedHashMap<>();m.put("stage",stage);m.put("userCode",mayRun?"may_have_started":"not_started");m.put("entrypointInvoked",invoked);return m;
+    }
+    static List<Map<String,Object>> diagnostics(List<Diagnostic<? extends JavaFileObject>> all,Source source){
+        List<Map<String,Object>> out=new ArrayList<>();
+        for(var d:all){
+            if(out.size()==MAX_DIAGNOSTICS)break;
+            Map<String,Object> v=new LinkedHashMap<>();v.put("severity",d.getKind().name().toLowerCase(Locale.ROOT));v.put("code",d.getCode());
+            String message=d.getMessage(Locale.ROOT);v.put("message",message.substring(0,Math.min(message.length(),512)));v.put("messageTruncated",message.length()>512);
+            v.put("line",d.getLineNumber()>0?d.getLineNumber():null);v.put("column",d.getColumnNumber()>0?d.getColumnNumber():null);
+            long userLine=d.getLineNumber()-source.prefixLines();v.put("sourceLine",userLine>0&&userLine<=source.userLines()?userLine:null);v.put("generatedWrapper",source.wrapped());out.add(v);
+        }
+        return out;
+    }
+    static void failure(Map<String,Object> out,String stage,Throwable error,String fallback){
+        out.put("success",false);
+        Throwable cause=error;
+        if(cause instanceof InvocationTargetException e&&e.getTargetException()!=null)cause=e.getTargetException();
+        String message=cause==null?fallback:cause.getClass().getSimpleName()+": "+Objects.toString(cause.getMessage(),"");
+        out.put("diagnostic",Map.of("kind",stage.equals("compile")?"java-compile":stage.equals("load")?"java-load":"java-"+stage,"message",message.substring(0,Math.min(message.length(),2048)),"messageTruncated",message.length()>2048));
+    }
+    public static void execute(Path requestFile,GhidraState state,TaskMonitor monitor)throws Exception {
+        JsonObject p=JsonParser.parseString(Files.readString(requestFile)).getAsJsonObject();
+        Path root=requestFile.toAbsolutePath().getParent();String code=p.get("code").getAsString(),attempt=p.get("attemptId").getAsString();
+        if(!sha(code).equals(p.get("sourceSha256").getAsString())||!attempt.matches("[a-f0-9-]{36}"))throw new IllegalArgumentException("Inline attempt binding differs");
+        Source source=source(code,attempt);BoundedOutput build=new BoundedOutput(),console=new BoundedOutput();
+        Map<String,Object> out=new LinkedHashMap<>();out.put("protocol","insight-inline-v1");out.put("attemptId",attempt);out.put("requestId",p.get("requestId").getAsString());out.put("sourceSha256",sha(code));out.put("success",false);
+        String stage="prepare";boolean mayRun=false;Object invoked=false;
+        PrintStream originalOut=System.out,originalErr=System.err;
+        PrintWriter scriptWriter=new PrintWriter(new OutputStreamWriter(console,StandardCharsets.UTF_8),true);
+        try {
+            JavaCompiler compiler=ToolProvider.getSystemJavaCompiler();if(compiler==null)throw new IllegalStateException("JDK Java compiler is unavailable");
+            Path file=root.resolve("source").resolve(source.name().replace('.','/')+".java"),classes=root.resolve("classes");
+            Files.createDirectories(file.getParent());Files.createDirectory(classes);Files.writeString(file,source.text(),StandardOpenOption.CREATE_NEW);
+            stage="compile";DiagnosticCollector<JavaFileObject> ds=new DiagnosticCollector<>();
+            try(StandardJavaFileManager manager=compiler.getStandardFileManager(ds,Locale.ROOT,StandardCharsets.UTF_8)){
+                // Compile only this immutable attempt. No source discovery or annotation/plugin execution.
+                List<String> options=List.of("-proc:none","-encoding","UTF-8","-classpath",System.getProperty("java.class.path"),"-sourcepath",root.resolve("source").toString(),"-d",classes.toString());
+                boolean ok=Boolean.TRUE.equals(compiler.getTask(new OutputStreamWriter(build,StandardCharsets.UTF_8),manager,ds,options,null,manager.getJavaFileObjects(file)).call());
+                out.put("diagnostics",diagnostics(ds.getDiagnostics(),source));out.put("diagnosticsTruncated",ds.getDiagnostics().size()>MAX_DIAGNOSTICS);
+                if(!ok){
+                    PrintWriter messages=new PrintWriter(new OutputStreamWriter(build,StandardCharsets.UTF_8));
+                    for(var d:ds.getDiagnostics())messages.println("Inline.java:"+d.getLineNumber()+":"+d.getColumnNumber()+": "+d.getKind()+": "+d.getMessage(Locale.ROOT));messages.flush();
+                    failure(out,stage,null,ds.getDiagnostics().stream().filter(d->d.getKind()==Diagnostic.Kind.ERROR).findFirst().map(d->d.getMessage(Locale.ROOT)).orElse("Java compilation failed"));return;
+                }
+            }
+            stage="load";
+            try(URLClassLoader loader=new URLClassLoader(new URL[]{classes.toUri().toURL()},InsightInlineExecutor.class.getClassLoader())){
+                // Resolution and reflection are performed without class initialization.
+                Class<?> type=Class.forName(source.name(),false,loader);
+                if(type.getClassLoader()!=loader)throw new IllegalArgumentException("Source class collides with a parent class");
+                if(!GhidraScript.class.isAssignableFrom(type)||Modifier.isAbstract(type.getModifiers())||!Modifier.isPublic(type.getModifiers()))throw new IllegalArgumentException("Inline class must be a public concrete GhidraScript");
+                Constructor<?> constructor=type.getDeclaredConstructor();if(!Modifier.isPublic(constructor.getModifiers()))throw new IllegalAccessException("Inline class needs a public default constructor");
+                // Set the conservative barrier BEFORE initialization or any caller-controlled method.
+                System.setOut(new PrintStream(console,true,StandardCharsets.UTF_8));System.setErr(System.out);
+                stage="initialize";mayRun=true;Class.forName(source.name(),true,loader);
+                stage="construct";
+                GhidraScript script=(GhidraScript)constructor.newInstance();
+                script.setSourceFile(new ResourceFile(file.toFile()));
+                String args=p.get("args").getAsString().trim();script.setScriptArgs(args.isEmpty()?new String[0]:args.split("\\s+"));
+                stage="execute";invoked=null; // Framework setup may fail before run(); never assert run() entry from an exception.
+                script.execute(state,monitor,scriptWriter);
+                out.put("success",true);
+            }
+        }catch(Throwable error){failure(out,stage,error,"Inline attempt failed");}
+        finally {
+            scriptWriter.flush();
+            System.setOut(originalOut);System.setErr(originalErr);
+            out.put("execution",execution(stage,mayRun,invoked));out.put("compilerOutput",build.value());out.put("console_output",console.text());out.put("outputTruncated",console.truncated);
+            Path receipt=root.resolve("receipt.json"),temporary=root.resolve("receipt.new");Files.writeString(temporary,JSON.toJson(out),StandardOpenOption.CREATE_NEW);
+            try(FileChannel channel=FileChannel.open(temporary,StandardOpenOption.WRITE)){channel.force(true);}
+            Files.move(temporary,receipt,StandardCopyOption.ATOMIC_MOVE);
+        }
+    }
+}

package/references/native/InsightInlineScript.java

@@ -0,0 +1,14 @@
+import ghidra.app.script.GhidraScript;
+import insight.InsightInlineExecutor;
+import java.nio.file.Path;
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+
+/** Only fixed trusted code is passed to the upstream script provider. User source is an input file. */
+public class InsightInlineScript extends GhidraScript {
+    public void run() throws Exception {
+        Path request=Path.of(new String(Base64.getDecoder().decode(getScriptArgs()[0]),StandardCharsets.UTF_8));
+        InsightInlineExecutor.execute(request,getState(),monitor);
+        println("INSIGHT_INLINE_COMPLETE");
+    }
+}

package/references/native/InsightPeRanges.java

@@ -0,0 +1,92 @@
+package com.eyeauras.insight;
+
+import java.math.BigInteger;
+import java.util.*;
+import java.util.function.LongSupplier;
+
+/** Current mapped PE32+/AMD64 runtime regions, never semantic function reconstruction. */
+public final class InsightPeRanges {
+  public record Span(BigInteger begin,BigInteger endExclusive,boolean execute) {}
+  public interface Bytes { int read(BigInteger at,byte[] out)throws Exception; }
+  public record Range(BigInteger begin,BigInteger endExclusive,BigInteger recordAddress) {
+    public Map<String,Object> facts(){return Map.of("source","pe-exception-directory","begin",begin.toString(16),"endExclusive",endExclusive.toString(16),"tableRecordAddress",recordAddress.toString(16),"semanticMembership","not-established","instructionBoundary","not-checked","unwindInfo","not-parsed");}
+  }
+  public record Result(Map<String,Object> lookup,List<Range> ranges) {}
+  private static final BigInteger U64=BigInteger.ONE.shiftLeft(64);
+  private final List<BigInteger> addresses;
+  private final BigInteger base;private final List<Span> spans;private final Bytes memory;private final LongSupplier clock;private final int maximum;private final long start;
+  private int bytesRead=0,recordsValidated=0;private long recordCount=0;
+  private static final class Stop extends Exception {final String state,reason;Stop(String s,String r){state=s;reason=r;}}
+  public InsightPeRanges(BigInteger base,List<Span> spans,Bytes memory,int maximum,LongSupplier clock,List<BigInteger> addresses){
+    this(base,spans,memory,maximum,clock,addresses,clock.getAsLong());
+  }
+  public InsightPeRanges(BigInteger base,List<Span> spans,Bytes memory,int maximum,LongSupplier clock,List<BigInteger> addresses,long started){
+    if(base.signum()<0||base.compareTo(U64)>=0||maximum<1||maximum>16777216)throw new IllegalArgumentException("Invalid PE lookup bounds");
+    if(addresses.size()>20)throw new IllegalArgumentException("At most 20 addresses");this.addresses=List.copyOf(addresses);
+    start=started;this.base=base;this.spans=spans.stream().sorted(Comparator.comparing(Span::begin)).toList();this.memory=memory;this.maximum=maximum;this.clock=clock;
+  }
+  private void tick()throws Stop {if(clock.getAsLong()-start>=5_000_000_000L)throw new Stop("incomplete","timeout");}
+  private boolean mapped(BigInteger at,long length,boolean execute)throws Stop {
+    BigInteger end=at.add(BigInteger.valueOf(length));if(length<1||at.signum()<0||end.compareTo(U64)>0)return false;
+    BigInteger cursor=at;
+    for(Span s:spans){tick();if(s.endExclusive.compareTo(cursor)<=0)continue;if(s.begin.compareTo(cursor)>0)return false;if(execute&&!s.execute)return false;cursor=s.endExclusive.min(end);if(cursor.equals(end))return true;}
+    return false;
+  }
+  private byte[] read(BigInteger at,int length,String missing)throws Exception {
+    tick();if(length>maximum-bytesRead)throw new Stop("incomplete","byte_limit");
+    if(!mapped(at,length,false))throw new Stop("unavailable",missing);
+    byte[] out=new byte[length];int got;
+    try{got=memory.read(at,out);}catch(Exception e){throw new Stop("unavailable","memory_read_failed");}
+    // A failed/short read never establishes absence. Charge every reported physical byte.
+    if(got<0||got>length)throw new IllegalStateException("Invalid native byte count");bytesRead+=got;
+    if(got!=length)throw new Stop("unavailable","short_read");tick();return out;
+  }
+  private static int u16(byte[] a,int i){return (a[i]&255)|((a[i+1]&255)<<8);}
+  private static long u32(byte[] a,int i){return Integer.toUnsignedLong((a[i]&255)|((a[i+1]&255)<<8)|((a[i+2]&255)<<16)|((a[i+3]&255)<<24));}
+  private void valid(boolean condition,String reason)throws Stop {if(!condition)throw new Stop("malformed",reason);}
+  private BigInteger rva(long offset,long size)throws Stop {valid(offset>0&&size>0&&offset+size<=0x1_0000_0000L,"invalid_rva");BigInteger at=base.add(BigInteger.valueOf(offset));valid(at.add(BigInteger.valueOf(size)).compareTo(U64)<=0,"address_overflow");return at;}
+  public Result run()throws Exception {
+    List<Range> ranges=new ArrayList<>();String state="validated",reason="validated";
+    try{
+      byte[] dos=read(base,64,"headers_not_mapped");valid(u16(dos,0)==0x5a4d,"invalid_dos_signature");long pe=u32(dos,60);valid(pe>=64,"invalid_pe_offset");
+      byte[] header=read(base.add(BigInteger.valueOf(pe)),24,"headers_not_mapped");valid(u32(header,0)==0x4550,"invalid_pe_signature");
+      if(u16(header,4)!=0x8664)throw new Stop("unavailable","unsupported_machine");
+      int optionalSize=u16(header,20);valid(optionalSize>=112,"short_optional_header");
+      byte[] optional=read(base.add(BigInteger.valueOf(pe+24)),112,"headers_not_mapped");
+      if(u16(optional,0)!=0x20b)throw new Stop("unavailable","unsupported_optional_header");
+      long imageSize=u32(optional,56),headerSize=u32(optional,60),directories=u32(optional,108);
+      valid(imageSize>0&&headerSize>=pe+24+optionalSize&&headerSize<=imageSize,"invalid_image_headers");
+      valid(directories<=(optionalSize-112)/8,"short_optional_header");
+      valid(base.add(BigInteger.valueOf(imageSize)).compareTo(U64)<=0,"address_overflow");
+      if(!mapped(base,pe+24+optionalSize,false))throw new Stop("unavailable","headers_not_mapped");
+      if(directories<4){state="absent";reason="no_exception_directory";}
+      else{
+        byte[] directory=read(base.add(BigInteger.valueOf(pe+24+136)),8,"headers_not_mapped");
+        long table=u32(directory,0),size=u32(directory,4);
+        if(table==0&&size==0){state="absent";reason="no_exception_directory";}
+        else{
+          valid(table>0&&size>0&&size%12==0&&table%4==0&&table+size<=imageSize,"invalid_exception_directory");
+          recordCount=size/12;BigInteger tableAt=rva(table,size);long previousEnd=0;
+          for(long offset=0;offset<size;){
+            tick();int length=(int)Math.min(4092,size-offset);byte[] chunk=read(tableAt.add(BigInteger.valueOf(offset)),length,"table_not_mapped");
+            for(int i=0;i<length;i+=12){
+              tick();long begin=u32(chunk,i),end=u32(chunk,i+4),unwind=u32(chunk,i+8);
+              valid(begin>0&&begin<end&&end<=imageSize,"invalid_runtime_range");
+              valid(begin>=previousEnd,"unordered_or_overlapping_ranges");
+              valid(unwind>0&&unwind<imageSize&&unwind%4==0,"invalid_unwind_rva");
+              BigInteger lo=rva(begin,end-begin);
+              if(!mapped(lo,end-begin,true))throw new Stop("unavailable","runtime_range_not_initialized_executable");
+              if(!mapped(rva(unwind,1),1,false))throw new Stop("unavailable","unwind_not_mapped");
+              BigInteger hi=base.add(BigInteger.valueOf(end));
+              if(addresses.stream().anyMatch(at->at.compareTo(lo)>=0&&at.compareTo(hi)<0))ranges.add(new Range(lo,hi,tableAt.add(BigInteger.valueOf(offset+i))));previousEnd=end;recordsValidated++;
+            }
+            offset+=length;
+          }
+        }
+      }
+      tick();
+    }catch(Stop e){state=e.state;reason=e.reason;ranges.clear();}
+    boolean complete=state.equals("validated")||state.equals("absent");
+    return new Result(Map.of("state",state,"complete",complete,"reason",reason,"headersSource","current-mapped-memory","recordCount",recordCount,"recordsValidated",recordsValidated,"bytesRead",bytesRead,"maximumBytes",maximum,"deadlineMilliseconds",5000),List.copyOf(ranges));
+  }
+}

package/references/native/InsightResearchQueries.java

@@ -111,6 +111,27 @@ public class InsightResearchQueries extends GhidraScript {
     candidates.add(map("address",currentProgram.getImageBase().toString(),"name","image_base","kind","image_base_candidate","confirmed",false,"provenance","program.image-base"));
     return map("entry_points",confirmed,"count",confirmed.size(),"candidates",candidates,"scan",scan(),"truncated",stopped,"semantics",map("kind","metadata","limitation","External-entry designation is Ghidra metadata, not proof of OS startup behavior; candidates are not confirmed entries."));
   }
+  Object navigation()throws Exception{
+    final int cap=128;int functions=0,oneByte=0,entryInstructions=0,instructions=0,references=0,data=0,strings=0;long bodyBytes=0;
+    var fs=currentProgram.getFunctionManager().getFunctions(true);
+    while(fs.hasNext()&&functions<cap){if(!visit())break;var f=fs.next();functions++;long size=f.getBody().getNumAddresses();bodyBytes+=size;if(size==1)oneByte++;if(currentProgram.getListing().getInstructionAt(f.getEntryPoint())!=null)entryInstructions++;}
+    boolean functionsComplete=!fs.hasNext();
+    var is=currentProgram.getListing().getInstructions(true);
+    while(is.hasNext()&&instructions<cap){if(!visit())break;is.next();instructions++;}boolean instructionsComplete=!is.hasNext();
+    var rs=currentProgram.getReferenceManager().getReferenceIterator(currentProgram.getMinAddress());
+    while(rs.hasNext()&&references<cap){if(!visit())break;rs.next();references++;}boolean referencesComplete=!rs.hasNext();
+    var ds=currentProgram.getListing().getDefinedData(true);
+    while(ds.hasNext()&&data<cap){if(!visit())break;var d=ds.next();data++;if(d.hasStringValue())strings++;}boolean dataComplete=!ds.hasNext();
+    boolean complete=functionsComplete&&instructionsComplete&&referencesComplete&&dataComplete;
+    String assessment=functions>0&&oneByte*5>=functions*4&&(functions-entryInstructions)*5>=functions*4?"sparse-metadata":functions==0&&instructions==0?"no-code-observed":"observed-metadata";
+    return map("functions",map("sampled",functions,"oneByteBodies",oneByte,"bodyBytes",bodyBytes,"entriesWithInstructions",entryInstructions,"complete",functionsComplete),
+      "instructions",map("sampled",instructions,"complete",instructionsComplete),"references",map("sampled",references,"complete",referencesComplete),
+      "definedData",map("sampled",data,"strings",strings,"complete",dataComplete),
+      "scan",map("visited",visited,"maximum",maxScan,"sampleLimitPerCategory",cap,"complete",complete,"reason",complete?"exhausted":stopped?"budget":"sample_limit"),
+      "assessment",assessment,"assessmentAlgorithm","one-byte-and-missing-entry-instruction-ratio-at-least-0.8-v1",
+      "recommendations",assessment.equals("sparse-metadata")||assessment.equals("no-code-observed")?List.of("Treat missing stored xrefs, strings and function containment as unknown. For known function entries try functions inspect --fields decompiled_code,callees; refresh stale/failed output with functions force-decompile --function <entry>.","For executable bytes without a function entry use functions decode. These reads do not repair Listing instructions or stored xrefs.","Find undefined literals with analysis search-byte-patterns and its next_address continuation; strings search visits defined data only.","Consider an explicit bounded analysis/disassembly Update only when needed; this diagnostic does not run analyzers."):List.of("Use observed metadata for navigation; verify individual bodies and references for the question under study."),
+      "coverage","At most 128 inputs per category, in address order, sharing max-scan and a five-second deadline. References are stored DB references; strings count only sampled defined data. Observations and heuristics do not prove analysis or semantic completeness.");
+  }
   Object strings(boolean search)throws Exception{
     List<Object> rows=new PagedRows();String needle=str(search?"search_term":"filter","");Pattern regex=search?safeRegex(needle):null;String encoding=str("encoding","");int min=number("min_length",search?4:0,0,65536);var iter=currentProgram.getListing().getDefinedData(true);
     while(iter.hasNext()){if(!visit())break;var d=iter.next();if(!d.hasStringValue())continue;if(d.getLength()>65536){stopped=true;break;}String value=Objects.toString(d.getValue(),"");if(value.length()>8192){stopped=true;break;}String enc=d.getDataType().getName().toLowerCase(Locale.ROOT).contains("unicode")?"unicode":"ascii";
@@ -203,7 +224,7 @@ public class InsightResearchQueries extends GhidraScript {
     if(consumed==input.length&&available<maximum&&reason.equals("byte_limit"))reason="executable_block_end";
     return map("address",start.toString(),"language",language,"compiler",currentProgram.getCompilerSpec().getCompilerSpecID().toString(),"input_bytes",HexFormat.of().formatHex(input),"input_sha256",HexFormat.of().formatHex(java.security.MessageDigest.getInstance("SHA-256").digest(input)),"maximum_bytes",maximum,"maximum_instructions",maxInstructions,"instructions",rows,"consumed_bytes",consumed,"stop_reason",reason,"truncated",List.of("byte_limit","instruction_limit","truncated_instruction","executable_block_end").contains(reason),"semantics","Linear pseudo instructions in the selected program context; direct targets are computed from bytes, not function membership or stored xrefs.");
   }
-  Object execute(String operation)throws Exception{return switch(operation){case "/research_view"->map("modification",Long.toString(currentProgram.getModificationNumber()),"language",currentProgram.getLanguageID().toString(),"compiler",currentProgram.getCompilerSpec().getCompilerSpecID().toString());case "/decode_instructions"->decodeInstructions();case "/find_dead_code"->dead();case "/detect_crypto_constants"->bytes(true);case "/search_byte_patterns"->bytes(false);case "/get_valid_data_types"->types(true);case "/find_data_types"->types(false);case "/validate_data_type"->validateType();case "/validate_function_prototype"->validatePrototype();case "/get_entry_points"->entries();case "/list_globals"->globals();case "/list_strings"->strings(false);case "/search_strings"->strings(true);case "/search_instructions"->instructions();default->throw new IllegalArgumentException("Unknown native query");};}
+  Object execute(String operation)throws Exception{return switch(operation){case "/navigation_diagnostic"->navigation();case "/research_view"->map("modification",Long.toString(currentProgram.getModificationNumber()),"language",currentProgram.getLanguageID().toString(),"compiler",currentProgram.getCompilerSpec().getCompilerSpecID().toString());case "/decode_instructions"->decodeInstructions();case "/find_dead_code"->dead();case "/detect_crypto_constants"->bytes(true);case "/search_byte_patterns"->bytes(false);case "/get_valid_data_types"->types(true);case "/find_data_types"->types(false);case "/validate_data_type"->validateType();case "/validate_function_prototype"->validatePrototype();case "/get_entry_points"->entries();case "/list_globals"->globals();case "/list_strings"->strings(false);case "/search_strings"->strings(true);case "/search_instructions"->instructions();default->throw new IllegalArgumentException("Unknown native query");};}
   public void run()throws Exception{
     var request=JsonParser.parseString(new String(Base64.getDecoder().decode(getScriptArgs()[0]),StandardCharsets.UTF_8)).getAsJsonObject();p=request.getAsJsonObject("parameters");maxScan=number("max_scan",100000,1,200000);limit=number("limit",100,1,1000);offset=number("offset",0,0,2000000);deadline=System.nanoTime()+number("timeout_seconds",5,1,30)*1000000000L;
     boundedMonitor=TimeoutTaskMonitor.timeoutIn(number("timeout_seconds",5,1,30),TimeUnit.SECONDS,monitor);

package/references/native/InsightResearchView.java

@@ -0,0 +1,69 @@
+package com.eyeauras.insight;
+
+import com.xebyte.core.*;
+import ghidra.program.model.listing.Program;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.address.Address;
+import java.math.BigInteger;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/** Precompiled, authenticated bridge read. Does not open, analyze, transact or save programs. */
+public final class InsightResearchView {
+  private final ProgramProvider programs;
+  private final ThreadingStrategy threading;
+  public InsightResearchView(ProgramProvider programs,ThreadingStrategy threading){this.programs=programs;this.threading=threading;}
+  private Program openProgram(String path){
+    if(programs==null||path==null||!path.startsWith("/")||path.length()>4096)throw new IllegalArgumentException("An explicit open program path is required");
+    Program selected=null;
+    for(Program p:programs.getAllOpenPrograms())if(p!=null&&!p.isClosed()&&p.getDomainFile()!=null&&path.equals(p.getDomainFile().getPathname())){
+      if(selected!=null&&selected!=p)throw new IllegalStateException("Program path is ambiguous");selected=p;
+    }
+    if(selected==null)throw new IllegalArgumentException("Program is not open");return selected;
+  }
+  @McpTool(path="/insight/research-view/v1",method="GET",description="Read modification/language/compiler of an already open program",access=ToolAccess.READ_ONLY)
+  public Response view(@Param(value="program",source=ParamSource.QUERY,allowEmpty=false) String path)throws Exception {
+    return threading.executeRead(()->{
+      Program selected=openProgram(path);
+      return Response.ok(Map.of("protocol","insight-research-view-v1","modification",Long.toString(selected.getModificationNumber()),"language",selected.getLanguageID().toString(),"compiler",selected.getCompilerSpec().getCompilerSpecID().toString()));
+    });
+  }
+  private static Map<String,Object> miss(String reason){return Map.of("status","not_found","reason",reason);}
+  private static Map<String,Object> resolved(Function function,Address at,String kind){
+    Map<String,Object> row=new LinkedHashMap<>();row.put("status","resolved");row.put("entryPoint",Long.toUnsignedString(function.getEntryPoint().getOffset(),16));
+    row.put("kind",kind);row.put("recordedBodyContainsAddress",function.getBody().contains(at));
+    if(!kind.equals("recorded-containing"))row.put("distanceBytes",at.subtract(function.getEntryPoint()));return row;
+  }
+  @McpTool(path="/insight/function-entries/v1",method="GET",description="Resolve up to 20 addresses using recorded bodies or a bounded preceding-entry candidate; no inferred membership",access=ToolAccess.READ_ONLY)
+  public Response entries(@Param(value="program",source=ParamSource.QUERY,allowEmpty=false) String path,
+      @Param(value="addresses",source=ParamSource.QUERY,allowEmpty=false) String addresses,
+      @Param(value="max_entry_distance",source=ParamSource.QUERY,allowEmpty=false) int maximum)throws Exception {
+    if(maximum<1||maximum>65536||addresses==null||addresses.length()>339)throw new IllegalArgumentException("Expected 1–20 addresses and a distance of 1–65536 bytes");
+    String[] words=addresses.split(",",-1);if(words.length<1||words.length>20)throw new IllegalArgumentException("Expected 1–20 addresses");
+    for(String word:words)if(!word.matches("[a-f0-9]{1,16}"))throw new IllegalArgumentException("Expected canonical default-space hexadecimal addresses");
+    return threading.executeRead(()->{
+      Program program=openProgram(path);long modification=program.getModificationNumber();var functions=program.getFunctionManager();
+      var space=program.getAddressFactory().getDefaultAddressSpace();var memory=program.getMemory();Map<String,Object> items=new LinkedHashMap<>();
+      for(String word:words){
+        if(items.containsKey(word)||!new BigInteger(word,16).toString(16).equals(word))throw new IllegalArgumentException("Expected distinct canonical addresses");
+        if(new BigInteger(word,16).bitLength()>space.getSize()){items.put(word,miss("address_out_of_range"));continue;}
+        Address at=space.getAddress(Long.parseUnsignedLong(word,16));
+        Function function=functions.getFunctionAt(at);
+        if(function!=null){items.put(word,resolved(function,at,"exact-entry"));continue;}
+        function=functions.getFunctionContaining(at);
+        if(function!=null){items.put(word,resolved(function,at,"recorded-containing"));continue;}
+        var block=memory.getBlock(at);
+        if(block==null||!block.isInitialized()||!block.isExecute()){items.put(word,miss("address_not_in_initialized_executable_block"));continue;}
+        // Address-seeded indexed iterator; consume at most one previous entry, never a full-table scan.
+        var previous=functions.getFunctions(at,false);
+        if(!previous.hasNext()){items.put(word,miss("no_preceding_entry"));continue;}
+        function=previous.next();Address entry=function.getEntryPoint();
+        if(!entry.getAddressSpace().equals(space)||entry.compareTo(at)>=0||!block.contains(entry)){items.put(word,miss("entry_outside_block"));continue;}
+        if(new BigInteger(word,16).subtract(new BigInteger(Long.toUnsignedString(entry.getOffset(),16),16)).compareTo(BigInteger.valueOf(maximum))>0){items.put(word,miss("entry_distance_exceeded"));continue;}
+        items.put(word,resolved(function,at,"preceding-entry-candidate"));
+      }
+      if(modification!=program.getModificationNumber())throw new IllegalStateException("Program changed during function-entry lookup");
+      return Response.ok(Map.of("protocol","insight-function-entries-v1","modification",Long.toString(modification),"items",items));
+    });
+  }
+}