@eyeauras/insight-cli 0.0.0-stage → 0.2.0

package/references/native/InsightTraceState.java

@@ -0,0 +1,130 @@
+import com.google.gson.*;
+import ghidra.app.script.GhidraScript;
+import ghidra.app.services.DebuggerTraceManagerService;
+import ghidra.app.services.DebuggerTargetService;
+import ghidra.app.services.DebuggerLogicalBreakpointService;
+import ghidra.app.services.DebuggerStaticMappingService;
+import ghidra.app.plugin.core.debug.utils.ProgramURLUtils;
+import ghidra.trace.model.Trace;
+import ghidra.framework.plugintool.PluginTool;
+import java.nio.file.*;
+import java.nio.charset.StandardCharsets;
+import java.util.*;
+import javax.swing.SwingUtilities;
+import ghidra.program.model.address.AddressSet;
+import ghidra.trace.model.memory.TraceMemoryState;
+
+/** Save/restore trace databases independently of the program database and live execution. */
+public class InsightTraceState extends GhidraScript {
+  static String string(JsonObject p,String key){return p.get(key).getAsString();}
+  static void bind(Trace trace,JsonObject p,boolean create){
+    var options=trace.getOptions("Insight");String target=options.getString("Target",null),context=options.getString("Context",null);
+    if(target==null&&context==null&&create){int tx=trace.startTransaction("Bind owned trace");try{
+      options.setString("Target",string(p,"target"));options.setString("Context",string(p,"context"));options.setString("Trace ID","trace_"+UUID.randomUUID());
+    }finally{trace.endTransaction(tx,true);}}
+    else if(!string(p,"target").equals(target)||!string(p,"context").equals(context))throw new IllegalArgumentException("Trace belongs to another context");
+  }
+  void relocateMappings(Trace trace,PluginTool tool)throws Exception{
+    var url=ProgramURLUtils.getUrlFromProgram(currentProgram);if(url==null)throw new IllegalStateException("Selected static program has no project URL");
+    var options=trace.getOptions("Insight");String previous=options.getString("Static Program URL",null);
+    if(previous==null||previous.equals(url.toExternalForm()))return;
+    var mappings=trace.getStaticMappingManager();int tx=trace.startTransaction("Relocate owned static mappings");boolean commit=false;
+    try{
+      for(var mapping:List.copyOf(mappings.getAllEntries()))if(previous.equals(mapping.getStaticProgramURL().toExternalForm())){
+        var range=mapping.getTraceAddressRange();var lifespan=mapping.getLifespan();String address=mapping.getStaticAddress();
+        mapping.delete();mappings.add(range,lifespan,url,address);
+      }
+      options.setString("Static Program URL",url.toExternalForm());commit=true;
+    }finally{trace.endTransaction(tx,commit);}
+    var service=tool.getService(DebuggerStaticMappingService.class);if(service==null)throw new IllegalStateException("Static mapping service unavailable");
+    service.changesSettled().get(30,java.util.concurrent.TimeUnit.SECONDS);
+  }
+  @Override public void run()throws Exception{
+    var p=JsonParser.parseString(new String(Base64.getDecoder().decode(getScriptArgs()[0]),StandardCharsets.UTF_8)).getAsJsonObject();
+    var project=state.getProject();DebuggerTraceManagerService manager=null;PluginTool selected=null;
+    for(PluginTool tool:project.getToolManager().getRunningTools()){
+      var candidate=tool.getService(DebuggerTraceManagerService.class);
+      if(candidate!=null&&(manager==null||!candidate.getOpenTraces().isEmpty())){manager=candidate;selected=tool;}
+    }
+    if(manager==null)throw new IllegalStateException("Debugger services unavailable");
+    var data=project.getProjectData();String operation=string(p,"operation");
+    if(Set.of("write_memory","write_register","timeline","objects","object_values","schedule").contains(operation)){
+      var trace=manager.getCurrentTrace();if(trace==null)throw new IllegalStateException("No selected trace");bind(trace,p,false);
+      Object value=insight.InsightTraceTools.run(trace,manager,selected,p,monitor);
+      String encoded=new GsonBuilder().serializeNulls().create().toJson(value);if(encoded.length()>524288)throw new IllegalArgumentException("Trace result exceeds 512 KiB");
+      println("INSIGHT_TRACE_STATE "+encoded);return;
+    }
+    if(operation.equals("breakpoints")){
+      var trace=manager.getCurrentTrace();if(trace==null)throw new IllegalStateException("No selected trace");bind(trace,p,false);
+      var service=selected.getService(DebuggerLogicalBreakpointService.class);if(service==null)throw new IllegalStateException("Breakpoint service unavailable");
+      List<Object> rows=new ArrayList<>();long snap=manager.getCurrentSnap();
+      for(var entry:service.getBreakpoints(trace).entrySet())for(var breakpoint:entry.getValue()){
+        rows.add(Map.of("address",entry.getKey().toString(),"name",breakpoint.getName(),"kinds",breakpoint.getKinds().stream().map(Enum::name).toList(),"state",breakpoint.computeState().name(),
+          "trace_location_count",breakpoint.getTraceBreakpoints(trace).stream().filter(location->!location.isDeleted()&&location.isValid(snap)).count()));
+      }
+      println("INSIGHT_TRACE_STATE "+new Gson().toJson(Map.of("items",rows)));return;
+    }
+    if(operation.equals("read_memory")){
+      var trace=manager.getCurrentTrace();if(trace==null)throw new IllegalStateException("No selected trace");bind(trace,p,false);
+      var at=trace.getBaseAddressFactory().getAddress(string(p,"address"));int size=p.get("size").getAsInt();if(at==null||size<1||size>4096)throw new IllegalArgumentException();
+      var targets=selected.getService(DebuggerTargetService.class);var target=targets==null?null:targets.getTarget(trace);
+      if(target!=null&&target.isValid())target.readMemory(new AddressSet(at,at.add(size-1)),monitor);
+      long snap=manager.getCurrentSnap();for(int i=0;i<size;i++)if(trace.getMemoryManager().getState(snap,at.add(i))!=TraceMemoryState.KNOWN)throw new IllegalStateException("Requested trace memory is not known");
+      println("INSIGHT_TRACE_STATE "+new Gson().toJson(Map.of("state","known")));return;
+    }
+    if(operation.equals("bind_new")){
+      var trace=manager.getCurrentTrace();if(trace==null||!trace.getName().equals(string(p,"name"))||trace.getOptions("Insight").getString("Trace ID",null)!=null)throw new IllegalStateException("New launch trace was not established");
+      bind(trace,p,true);var url=ProgramURLUtils.getUrlFromProgram(currentProgram);if(url==null)throw new IllegalStateException("Selected static program has no project URL");
+      int tx=trace.startTransaction("Bind owned static program");try{trace.getOptions("Insight").setString("Static Program URL",url.toExternalForm());trace.getOptions("Insight").setString("Owned Context Root",string(p,"owned_root"));}finally{trace.endTransaction(tx,true);}
+      println("INSIGHT_TRACE_STATE "+new Gson().toJson(Map.of("state","bound")));return;
+    }
+    if(operation.equals("focus")){
+      var thread=manager.getCurrentThread();var object=thread==null?null:thread.getObject();
+      if(object==null){var candidates=manager.getCurrentTrace().getObjectManager().getAllObjects().filter(item->item.getSchema().getName().toString().equals("Process")).toList();
+        if(candidates.size()!=1)throw new IllegalStateException("Debugger process selection is ambiguous");object=candidates.get(0);}
+      var m=manager;final var selectedObject=object;Runnable focus=()->m.activateObject(selectedObject);
+      if(SwingUtilities.isEventDispatchThread())focus.run();else SwingUtilities.invokeAndWait(focus);
+      println("INSIGHT_TRACE_STATE "+new Gson().toJson(Map.of("state","focused")));return;
+    }
+    if(operation.equals("restore")){
+      var folder=data.getRootFolder().getFolder("__insight_traces");if(folder==null)folder=data.getRootFolder().createFolder("__insight_traces");
+      for(var entry:p.getAsJsonArray("traces")){
+        var saved=entry.getAsJsonObject();String id=string(saved,"id");if(!id.matches("trace_[a-f0-9-]{36}"))throw new IllegalArgumentException();
+        boolean present=false;for(var trace:manager.getOpenTraces())if(id.equals(trace.getOptions("Insight").getString("Trace ID",null)))present=true;
+        if(present)continue;
+        var file=folder.getFile(id);if(file==null)file=folder.createFile(id,Path.of(string(saved,"input")).toFile(),monitor);
+        Trace trace=manager.openTrace(file,-1);bind(trace,p,false);
+        if(!id.equals(trace.getOptions("Insight").getString("Trace ID",null)))throw new IllegalArgumentException("Restored trace identity changed");
+        relocateMappings(trace,selected);
+        if(p.has("active")&&id.equals(string(p,"active"))){final var m=manager;Runnable activate=()->{
+          m.activateTrace(trace);m.activateSnap(Long.parseLong(string(saved,"snap")));
+          if(saved.has("thread")){var thread=trace.getThreadManager().getThread(Long.parseLong(string(saved,"thread")));if(thread!=null)m.activateThread(thread);}
+        };if(SwingUtilities.isEventDispatchThread())activate.run();else SwingUtilities.invokeAndWait(activate);}
+      }
+      println("INSIGHT_TRACE_STATE "+new Gson().toJson(Map.of("state","restored")));return;
+    }
+    if(operation.equals("select")){
+      String id=string(p,"id");for(var trace:manager.getOpenTraces()){
+        bind(trace,p,false);if(id.equals(trace.getOptions("Insight").getString("Trace ID",null))){final var m=manager;
+          if(SwingUtilities.isEventDispatchThread())m.activateTrace(trace);else SwingUtilities.invokeAndWait(()->m.activateTrace(trace));
+          println("INSIGHT_TRACE_STATE "+new Gson().toJson(Map.of("state","selected","id",id)));return;}
+      }
+      throw new IllegalArgumentException("Trace not found");
+    }
+    if(!operation.equals("checkpoint"))throw new IllegalArgumentException();
+    Path root=Path.of(string(p,"output")).toRealPath();List<Object> traces=new ArrayList<>();String active=null;
+    if(manager.getOpenTraces().size()>64)throw new IllegalArgumentException("Trace count exceeds 64");
+    for(var trace:manager.getOpenTraces()){
+      bind(trace,p,false);String id=trace.getOptions("Insight").getString("Trace ID",null);if(id==null||!id.matches("trace_[a-f0-9-]{36}"))throw new IllegalArgumentException();
+      Path output=root.resolve(id+".gzf");if(Files.exists(output))throw new IllegalArgumentException();
+      var coordinates=manager.getCurrentFor(trace);trace.saveToPackedFile(output.toFile(),monitor);
+      Map<String,Object> row=new LinkedHashMap<>();row.put("id",id);row.put("name",trace.getName());row.put("snap",Long.toString(coordinates.getSnap()));
+      row.put("modules",trace.getModuleManager().getAllModules().size());row.put("threads",trace.getThreadManager().getAllThreads().size());
+      if(coordinates.getThread()!=null)row.put("thread",Long.toString(coordinates.getThread().getKey()));
+      var targets=selected.getService(DebuggerTargetService.class);var live=targets==null?null:targets.getTarget(trace);row.put("connected",live!=null&&live.isValid());
+      traces.add(row);if(manager.getCurrentTrace()==trace)active=id;
+    }
+    Map<String,Object> result=new LinkedHashMap<>();result.put("traces",traces);if(active!=null)result.put("active",active);
+    println("INSIGHT_TRACE_STATE "+new Gson().toJson(result));
+  }
+}

package/references/native/InsightTraceTools.java

@@ -0,0 +1,114 @@
+package insight;
+
+import com.google.gson.*;
+import ghidra.app.services.*;
+import ghidra.debug.api.target.Target;
+import ghidra.framework.plugintool.PluginTool;
+import ghidra.program.model.address.*;
+import ghidra.program.model.lang.*;
+import ghidra.trace.model.*;
+import ghidra.trace.model.memory.*;
+import ghidra.trace.model.target.*;
+import ghidra.trace.model.target.path.KeyPath;
+import ghidra.trace.model.time.schedule.TraceSchedule;
+import ghidra.trace.model.time.TraceSnapshot;
+import ghidra.util.task.TaskMonitor;
+import java.util.*;
+import java.math.BigInteger;
+import java.nio.ByteBuffer;
+import java.util.concurrent.TimeUnit;
+
+/** Typed trace inspection and guarded live-target writes. Trace cache writes never substitute for target writes. */
+public class InsightTraceTools {
+    static String text(JsonObject p,String key){return p.has(key)?p.get(key).getAsString():"";}
+    static int bound(JsonObject p,String key,int fallback,int maximum){int n=p.has(key)?p.get(key).getAsInt():fallback;if(n<1||n>maximum)throw new IllegalArgumentException("Invalid trace work bound");return n;}
+    static void require(boolean value,String message){if(!value)throw new IllegalStateException(message);}
+    static byte[] hex(String text){if(!text.matches("(?:[a-f0-9A-F]{2}){1,4096}"))throw new IllegalArgumentException("Expected 1–4096 complete byte pairs");return HexFormat.of().parseHex(text);}
+    static BigInteger integer(String text){if(!text.matches("(?:0[xX])?[a-f0-9A-F]{1,128}"))throw new IllegalArgumentException("Expected unsigned hex register value");return new BigInteger(text.replaceFirst("(?i)^0x",""),16);}
+    static Object value(Object value){
+        if(value instanceof TraceObject object)return Map.of("kind","object","object_id",Long.toString(object.getKey()),"path",object.getCanonicalPath().toString(),"schema",object.getSchema().getName().toString());
+        if(value instanceof Address at)return Map.of("kind","address","space",at.getAddressSpace().getName(),"address",at.toString());
+        if(value instanceof AddressRange range)return Map.of("kind","address_range","start",range.getMinAddress().toString(),"end",range.getMaxAddress().toString());
+        if(value instanceof Number)return Map.of("kind","number","value",value.toString());
+        if(value instanceof Boolean)return Map.of("kind","boolean","value",value);
+        if(value instanceof String string)return Map.of("kind","string","value",string.substring(0,Math.min(4096,string.length())),"complete",string.length()<=4096);
+        if(value instanceof byte[] bytes)return Map.of("kind","bytes","hex",HexFormat.of().formatHex(Arrays.copyOf(bytes,Math.min(bytes.length,4096))),"size",bytes.length,"complete",bytes.length<=4096);
+        return Map.of("kind","unsupported","java_type",value==null?"null":value.getClass().getSimpleName());
+    }
+    static Target live(Trace trace,DebuggerTraceManagerService manager,PluginTool tool){
+        var targets=tool.getService(DebuggerTargetService.class);Target target=targets==null?null:targets.getTarget(trace);
+        require(target!=null&&target.isValid(),"Selected trace is disconnected");var coords=manager.getCurrentFor(trace);
+        require(coords.getTime().isSnapOnly()&&coords.getSnap()==target.getSnap(),"Write requires the current live snapshot, not historical/emulated time");
+        require(coords.getThread()!=null&&target.getThreadExecutionState(coords.getThread())==TraceExecutionState.STOPPED,"Write requires a selected stopped thread");return target;
+    }
+    static byte[] memory(Trace trace,Target target,Address at,int size,TaskMonitor monitor)throws Exception{
+        target.readMemoryAsync(new AddressSet(at,at.add(size-1)),monitor).get(30,TimeUnit.SECONDS);long snap=target.getSnap();
+        var memory=trace.getMemoryManager();for(int i=0;i<size;i++)require(memory.getState(snap,at.add(i))==TraceMemoryState.KNOWN,"Fresh target memory is not known");
+        ByteBuffer bytes=ByteBuffer.allocate(size);require(memory.getBytes(snap,at,bytes)==size,"Fresh target memory is incomplete");return bytes.array();
+    }
+    public static Object run(Trace trace,DebuggerTraceManagerService manager,PluginTool tool,JsonObject p,TaskMonitor monitor)throws Exception{
+        boolean[] targetEffect={false};try{Object result=operation(trace,manager,tool,p,monitor,targetEffect);JsonElement json=new Gson().toJsonTree(result);
+            String original=trace.getOptions("Insight").getString("Owned Context Root",text(p,"owned_root"));return logical(json,original,text(p,"owned_root"));}
+        catch(Exception failure){String operation=text(p,"operation");if((operation.equals("write_memory")||operation.equals("write_register"))&&!targetEffect[0]){
+            String diagnostic=failure.getStackTrace().length>0&&failure.getStackTrace()[0].getClassName().equals("insight.InsightTraceTools")?Objects.toString(failure.getMessage(),failure.getClass().getSimpleName()):failure.getClass().getSimpleName();
+            return Map.of("status","rejected","target_effect_started",false,"reason","native_live_precondition_changed","diagnostic",diagnostic);}
+            throw failure;}
+    }
+    static JsonElement logical(JsonElement value,String original,String current){
+        if(value.isJsonPrimitive()&&value.getAsJsonPrimitive().isString()){String text=value.getAsString();if(!original.isEmpty())text=text.replace(original,"@target");if(!current.isEmpty())text=text.replace(current,"@target");return new JsonPrimitive(text);}
+        if(value.isJsonArray()){JsonArray result=new JsonArray();for(JsonElement child:value.getAsJsonArray())result.add(logical(child,original,current));return result;}
+        if(value.isJsonObject()){JsonObject result=new JsonObject();for(var entry:value.getAsJsonObject().entrySet())result.add(entry.getKey(),logical(entry.getValue(),original,current));return result;}return value;
+    }
+    static Object operation(Trace trace,DebuggerTraceManagerService manager,PluginTool tool,JsonObject p,TaskMonitor monitor,boolean[] targetEffect)throws Exception{
+        String operation=text(p,"operation");long snap=p.has("snap")?Long.parseLong(text(p,"snap")):manager.getCurrentSnap();
+        if(operation.equals("write_memory")){
+            Target target=live(trace,manager,tool);byte[] expected=hex(text(p,"expect_hex")),wanted=hex(text(p,"bytes_hex"));if(expected.length!=wanted.length)throw new IllegalArgumentException("Expected/replacement lengths differ");
+            Address at=trace.getBaseAddressFactory().getAddress(text(p,"address"));if(at==null)throw new IllegalArgumentException("Invalid trace address");
+            require(Arrays.equals(memory(trace,target,at,expected.length,monitor),expected),"Live memory byte precondition changed");
+            targetEffect[0]=true;target.writeMemoryAsync(at,wanted).get(30,TimeUnit.SECONDS);require(Arrays.equals(memory(trace,target,at,wanted.length,monitor),wanted),"Fresh live memory readback differs");
+            return Map.of("status","written","address",at.toString(),"size",wanted.length,"bytes_hex",HexFormat.of().formatHex(wanted),"verified_from","live_target_refresh","snap",Long.toString(target.getSnap()));
+        }
+        if(operation.equals("write_register")){
+            Target target=live(trace,manager,tool);var coords=manager.getCurrentFor(trace);var platform=coords.getPlatform();Register register=platform.getLanguage().getRegister(text(p,"register"));
+            if(register==null)throw new IllegalArgumentException("Unknown platform register");BigInteger expected=integer(text(p,"expect_value")),wanted=integer(text(p,"value"));
+            if(expected.bitLength()>register.getBitLength()||wanted.bitLength()>register.getBitLength())throw new IllegalArgumentException("Register value exceeds its exact width");
+            target.readRegistersAsync(platform,coords.getThread(),coords.getFrame(),Set.of(register)).get(30,TimeUnit.SECONDS);
+            var space=trace.getMemoryManager().getMemoryRegisterSpace(coords.getThread(),coords.getFrame(),false);require(space!=null,"Selected register bank is absent");
+            var observed=space.getViewValue(platform,target.getSnap(),register);require(observed!=null&&observed.hasValue()&&expected.equals(observed.getUnsignedValue()),"Live register precondition changed");
+            targetEffect[0]=true;target.writeRegisterAsync(platform,coords.getThread(),coords.getFrame(),new RegisterValue(register,wanted)).get(30,TimeUnit.SECONDS);
+            target.readRegistersAsync(platform,coords.getThread(),coords.getFrame(),Set.of(register)).get(30,TimeUnit.SECONDS);observed=space.getViewValue(platform,target.getSnap(),register);
+            require(observed!=null&&observed.hasValue()&&wanted.equals(observed.getUnsignedValue()),"Fresh live register readback differs");
+            return Map.of("status","written","register",register.getName(),"value","0x"+wanted.toString(16),"bits",register.getBitLength(),"verified_from","live_target_refresh","snap",Long.toString(target.getSnap()));
+        }
+        if(operation.equals("timeline")){
+            long before=p.has("before_snap")?Long.parseLong(text(p,"before_snap")):Long.MAX_VALUE;int limit=bound(p,"limit",100,1000);List<Object> rows=new ArrayList<>();boolean complete=false;
+            for(int i=0;i<limit;i++){monitor.checkCancelled();TraceSnapshot snapshot=trace.getTimeManager().getMostRecentSnapshot(before);if(snapshot==null){complete=true;break;}
+                Map<String,Object> row=new LinkedHashMap<>();row.put("snap",Long.toString(snapshot.getKey()));row.put("description",snapshot.getDescription());row.put("schedule",snapshot.getScheduleString());row.put("real_time",Long.toString(snapshot.getRealTime()));
+                row.put("event_thread",snapshot.getEventThread()==null?null:Long.toString(snapshot.getEventThread().getKey()));rows.add(row);
+                if(snapshot.getKey()==Long.MIN_VALUE){complete=true;break;}before=snapshot.getKey()-1;}
+            Map<String,Object> out=new LinkedHashMap<>();out.put("items",rows);out.put("complete",complete);if(!complete)out.put("next_before_snap",Long.toString(before));return out;
+        }
+        if(operation.equals("objects")){
+            int limit=bound(p,"limit",100,1000),budget=bound(p,"max_scan",10000,200000),visited=0;List<Object> rows=new ArrayList<>();String prefix=text(p,"path_prefix").replace("@target",trace.getOptions("Insight").getString("Owned Context Root",text(p,"owned_root")));
+            try(var stream=trace.getObjectManager().getAllObjects()){var iterator=stream.iterator();
+                while(iterator.hasNext()&&rows.size()<limit&&visited<budget){monitor.checkCancelled();TraceObject object=iterator.next();visited++;
+                    if(object.isAlive(snap)&&object.getCanonicalPath().toString().startsWith(prefix))rows.add(Map.of("object_id",Long.toString(object.getKey()),"path",object.getCanonicalPath().toString(),"schema",object.getSchema().getName().toString(),"life",object.getLife().toString()));}
+                return Map.of("snap",Long.toString(snap),"items",rows,"visited",visited,"complete",!iterator.hasNext());}
+        }
+        if(operation.equals("object_values")){
+            TraceObject object=trace.getObjectManager().getObjectById(Long.parseLong(text(p,"object_id")));if(object==null)throw new IllegalArgumentException("Trace object ID is absent");
+            String key=text(p,"key");long from=p.has("from_snap")?Long.parseLong(text(p,"from_snap")):snap,to=p.has("to_snap")?Long.parseLong(text(p,"to_snap")):from;
+            if(to<from||BigInteger.valueOf(to).subtract(BigInteger.valueOf(from)).compareTo(BigInteger.valueOf(999))>0)throw new IllegalArgumentException("Value history range is 1–1000 snaps");
+            List<Object> rows=new ArrayList<>();String previous="";
+            for(long current=from;;current++){monitor.checkCancelled();TraceObjectValue entry=object.getValue(current,key);
+                if(entry!=null&&!entry.getLifespan().toString().equals(previous)){rows.add(Map.of("key",key,"lifespan",entry.getLifespan().toString(),"value",value(entry.getValue())));previous=entry.getLifespan().toString();}
+                if(current==to)break;}
+            return Map.of("object_id",Long.toString(object.getKey()),"path",object.getCanonicalPath().toString(),"key",key,"from_snap",Long.toString(from),"to_snap",Long.toString(to),"items",rows,"complete",true);
+        }
+        if(operation.equals("schedule")){
+            TraceSchedule schedule=TraceSchedule.parse(text(p,"schedule"));schedule.validate(trace);
+            return Map.of("schedule",schedule.toString(),"base_snap",Long.toString(schedule.getSnap()),"ticks",Long.toString(schedule.totalTickCount()),"patches",Long.toString(schedule.totalPatchCount()),"snap_only",schedule.isSnapOnly(),"validated",true,"executed",false);
+        }
+        throw new IllegalArgumentException("Unknown typed trace operation");
+    }
+}

package/references/native/InsightVersionTracking.java

@@ -0,0 +1,91 @@
+import com.google.gson.*;
+import ghidra.GhidraApplicationLayout;
+import ghidra.framework.*;
+import ghidra.framework.model.*;
+import ghidra.base.project.GhidraProject;
+import ghidra.program.model.listing.*;
+import ghidra.program.model.address.*;
+import ghidra.feature.vt.api.db.VTSessionDB;
+import ghidra.feature.vt.api.main.*;
+import ghidra.feature.vt.api.correlator.program.*;
+import ghidra.util.task.*;
+import java.util.*;
+import java.util.concurrent.TimeUnit;
+import java.nio.file.*;
+import java.nio.channels.FileChannel;
+
+/** Persistent native VT session with owned source/destination programs, never caller GPR paths. */
+class InsightVersionTracking {
+    static String text(JsonObject p,String key){return p.has(key)?p.get(key).getAsString():"";}
+    static Map<String,Object> match(VTMatch value){var association=value.getAssociation();return Map.of("set_id",value.getMatchSet().getID(),
+        "source",value.getSourceAddress().toString(),"destination",value.getDestinationAddress().toString(),
+        "similarity",value.getSimilarityScore().getScore(),"confidence",value.getConfidenceScore().getScore(),
+        "status",association.getStatus().toString(),"type",association.getType().toString(),"markup_status",association.getMarkupStatus().toString());}
+    static Object matches(VTSessionDB session,JsonObject p){
+        int limit=p.has("limit")?p.get("limit").getAsInt():100,offset=p.has("offset")?p.get("offset").getAsInt():0,total=0;List<Object> rows=new ArrayList<>(),sets=new ArrayList<>();Set<Address> sourceMatches=new HashSet<>(),destinationMatches=new HashSet<>();
+        for(var set:session.getMatchSets()){
+            sets.add(Map.of("id",set.getID(),"correlator",set.getProgramCorrelatorInfo().getName(),"count",set.getMatchCount()));
+            for(var value:set.getMatches()){sourceMatches.add(value.getSourceAddress());destinationMatches.add(value.getDestinationAddress());if(total++<offset)continue;if(rows.size()<limit)rows.add(match(value));}}
+        return Map.of("match_sets",sets,"items",rows,"total",total,"offset",offset,"limit",limit,"complete",offset+rows.size()>=total,
+            "unmatched_source",unmatched(session.getSourceProgram(),sourceMatches),"unmatched_destination",unmatched(session.getDestinationProgram(),destinationMatches),
+            "score_semantics","Native VT scores are correlator-specific, not calibrated probabilities. Unmatched means no association from these configured correlators, not proof of no equivalent function.");
+    }
+    static Object unmatched(Program program,Set<Address> matched){List<Object> rows=new ArrayList<>();int total=0;var iterator=program.getFunctionManager().getFunctions(true);
+        while(iterator.hasNext()){Function function=iterator.next();if(matched.contains(function.getEntryPoint()))continue;if(total++<1000)rows.add(Map.of("name",function.getName(),"address",function.getEntryPoint().toString()));}
+        return Map.of("items",rows,"total",total,"complete",total<=1000);}
+    static VTAssociation association(VTSessionDB session,JsonObject p){
+        Address from=session.getSourceProgram().getAddressFactory().getAddress(text(p,"source_address")),to=session.getDestinationProgram().getAddressFactory().getAddress(text(p,"destination_address"));
+        if(from==null||to==null)throw new IllegalArgumentException("Invalid VT association addresses");
+        for(var set:session.getMatchSets())for(var value:set.getMatches())if(value.getSourceAddress().equals(from)&&value.getDestinationAddress().equals(to))return value.getAssociation();
+        throw new IllegalArgumentException("VT association is not in this session");
+    }
+    static Object markup(VTAssociation association,TaskMonitor monitor)throws Exception{
+        List<Object> rows=new ArrayList<>();for(var item:association.getMarkupItems(monitor)){
+            if(rows.size()>=1000)throw new IllegalArgumentException("Markup inventory exceeds 1000 items");Map<String,Object> row=new LinkedHashMap<>();
+            row.put("type",item.getMarkupType().getDisplayName());row.put("source",item.getSourceAddress().toString());row.put("destination",item.getDestinationAddress()==null?null:item.getDestinationAddress().toString());
+            row.put("source_value",Objects.toString(item.getSourceValue(),null));row.put("destination_value",Objects.toString(item.getCurrentDestinationValue(),null));
+            row.put("status",item.getStatus().toString());row.put("can_apply",item.canApply());rows.add(row);}
+        return Map.of("items",rows,"association_status",association.getStatus().toString(),"read_only",true);
+    }
+    static Object run(JsonObject p)throws Exception{
+        String operation=text(p,"operation"),root=text(p,"root");Object consumer=new Object();GhidraProject project=null;VTSessionDB session=null;Program source=null,destination=null;
+        TimeoutTaskMonitor monitor=TimeoutTaskMonitor.timeoutIn(60,TimeUnit.SECONDS);
+        try{
+            project=operation.equals("create")?GhidraProject.createProject(root,"project",false):GhidraProject.openProject(root,"project",false);
+            var data=project.getProjectData();
+            if(operation.equals("create")){
+                DomainFile first=data.getRootFolder().createFile("Source",Path.of(text(p,"source_snapshot")).toFile(),monitor);
+                DomainFile second=data.getRootFolder().createFile("Destination",Path.of(text(p,"destination_snapshot")).toFile(),monitor);
+                source=(Program)first.getDomainObject(consumer,true,false,monitor);destination=(Program)second.getDomainObject(consumer,true,false,monitor);
+                if(source.getFunctionManager().getFunctionCount()>10000||destination.getFunctionManager().getFunctionCount()>10000)throw new IllegalArgumentException("VT workflow accepts at most 10000 functions per input");
+                session=new VTSessionDB("OwnedVersionTracking",source,destination,consumer);int transaction=session.startTransaction("Correlate owned versions");boolean committed=false;
+                try{
+                    var exact=new ExactMatchBytesProgramCorrelatorFactory();var options=exact.createDefaultOptions();options.setInt(ExactMatchBytesProgramCorrelatorFactory.FUNCTION_MINIMUM_SIZE,1);
+                    exact.createCorrelator(source,source.getMemory(),destination,destination.getMemory(),options).correlate(session,monitor);
+                    var duplicates=new DuplicateFunctionMatchProgramCorrelatorFactory();duplicates.createCorrelator(source,source.getMemory(),destination,destination.getMemory(),duplicates.createDefaultOptions()).correlate(session,monitor);
+                    committed=true;
+                }finally{session.endTransaction(transaction,committed);}
+                data.getRootFolder().createFile("Session",session,monitor);
+            }else{
+                DomainFile file=data.getFile("/Session");if(file==null)throw new IllegalArgumentException("Native VT session is absent");session=(VTSessionDB)file.getDomainObject(consumer,true,false,monitor);
+            }
+            Object result;
+            if(operation.equals("create")||operation.equals("matches"))result=matches(session,p);
+            else if(operation.equals("markup"))result=markup(association(session,p),monitor);
+            else if(operation.equals("decide")){
+                VTAssociation value=association(session,p);String decision=text(p,"decision");int transaction=session.startTransaction("Explicit match decision");boolean committed=false,closed=false;
+                try{switch(decision){case "accepted":value.setAccepted();break;case "rejected":value.setRejected();break;case "available":value.clearStatus();break;default:throw new IllegalArgumentException("Unknown match decision");}committed=true;}
+                catch(Exception rejected){closed=true;session.endTransaction(transaction,false);return Map.of("state","rejected","reason","native_association_constraint");}
+                finally{if(!closed)session.endTransaction(transaction,committed);}
+                session.save("Explicit facade match decision",monitor);result=Map.of("source",value.getSourceAddress().toString(),"destination",value.getDestinationAddress().toString(),"status",value.getStatus().toString());
+            }else throw new IllegalArgumentException("Unknown VT operation");
+            return result;
+        }finally{monitor.finished();if(session!=null)session.release(consumer);if(source!=null)source.release(consumer);if(destination!=null)destination.release(consumer);if(project!=null)project.close();}
+    }
+    public static void main(String[] args){var output=System.out;System.setOut(System.err);
+        try{Application.initializeApplication(new GhidraApplicationLayout(),new HeadlessGhidraApplicationConfiguration());JsonObject p=JsonParser.parseString(Files.readString(Path.of(args[0]))).getAsJsonObject();Object value=run(p);
+            InsightNativeReceipt.write(p,value);
+            output.println(new GsonBuilder().serializeNulls().create().toJson(Map.of("value",value)));System.exit(0);
+        }catch(Throwable failure){failure.printStackTrace(System.err);output.println("{\"error\":\"native_version_tracking_failed\"}");System.exit(1);}
+    }
+}

package/references/native-workflows.md

@@ -0,0 +1,112 @@
+# Selected native SDK workflows
+
+These commands extend the pinned MCP catalog. All program calls select both `--session` and
+`--target`; API callers use the same Factory command paths. Use generated help for flags.
+Programs remain private until explicit `ghidra merge`. Every new program edit is a complex
+change: saved-state verification is required, and a diverged shared base retains a conflict.
+`refresh` does not silently overwrite either complex version. Program edits require Destructive
+permission. File/database creation and VT decisions require Update; reads require ReadOnly.
+
+## Compare and edit a private program
+
+`ghidra changes compare --other-target <id> --other-session <id>` compares immutable saved
+contexts with native ProgramDiff. Choose `--categories '["bytes","comments","symbols"]'`;
+other supported categories are code_units, functions, references, context and properties.
+Results retain address ranges and completion flags. This does not run a universal DB merger.
+
+`ghidra memory patch-bytes --address 0x180000000 --expect-hex 9090 --bytes-hex 9091`
+requires equal lengths of 1–4096 bytes and clears overlapping listing. `assembly preview` takes
+`--instructions '["NOP"]'`; `assembly apply` also requires exact `--expect-hex`. Assembly uses
+the selected program's language and processor context. It does not rebuild executable files.
+
+`memory block-state --name <block>` returns current layout and a full digest for initialized
+blocks up to 16 MiB. `split-block` and `move-block` require that digest, size and original start;
+`join-blocks` requires both sizes/digests and compatible adjacent blocks. No uninitialized or
+oversized-block edit is implied. `processor-context read|set|clear` addresses a named register
+and a range of at most 65536 bytes. Read distinguishes explicit state from compiler defaults.
+
+`namespaces list|create|update|delete` supports ordinary namespaces/classes; deletion requires
+an empty container. `externals` supplies create/update/delete-library and create/update/delete-location.
+Deletion refuses retained dependencies. It does not recursively erase referenced program state.
+
+`decompiler ir --address <function> --simplification normalize --max-ops 1000` returns typed SSA
+operations, varnodes, address spaces, sizes and block IDs. Options are known Boolean keys:
+eliminate_unreachable, respect_read_only, infer_constant_pointers, split_structures, split_arrays.
+Native timeout is 1–120 seconds. `completed` describes decompilation; `ir_complete` separately
+reports a truncated operation list. The result is a bounded view, not a serialized HighFunction graph.
+
+## Loader, exporter and type archives
+
+`ghidra formats loaders --input <file>` consumes immutable bytes and lists actual installed
+loader IDs, supported language/compiler specifications and native option definitions.
+`ghidra open <file> --session new --loader BinaryLoader --language x86:LE:64:default
+--loader-options '{"Base Address":"0x10000","File Offset":"0x2","Length":"0x6"}'`
+selects a loader explicitly. Primitive options, native address and HexLong options are converted
+and validated; unsupported complex option classes fail explicitly. One program belongs to a target.
+
+`formats exporters` lists compatible native exporters and their options. `formats export
+--exporter 'Raw Bytes' --ranges '[{"start":"0x10001","end":"0x10003"}]'
+--output-directory <new-directory>` requires a format supporting restricted address sets.
+All output/companion files are hashed and retained. Existing destinations are not overwritten.
+Native completion receipts permit a repeated request ID to recover completed bytes without
+another export. An incomplete/uncertain export cannot be replayed blindly.
+
+`types define-layout --path /Owned/Record --packing 1 --fields
+'[{"name":"flags","type":"uint","bit_size":3},{"name":"value","type":"ushort"}]'`
+uses native structures and bitfields. Packing/alignment accept -1, zero or powers of two through
+64; explicit byte offsets require packing -1. There are at most 256 fields. `types layout` returns
+native source archive/universal IDs and bounded field/setting records. `types set-settings --path
+/Owned/Number --settings '{"Format":1}'` uses actual definition names and native enum choices;
+null clears an explicit setting. Inventory the type first; definitions differ between native types.
+
+`types archive-export --types '["/Owned/Record"]' --output-directory <new-directory>` creates a
+real GDT. `types archive-import --input <file.gdt> --types '["/Owned/Record"]'` consumes an
+immutable archive up to 64 MiB and checks saved layout/source identity. A conflicting existing
+layout is rejected. `types create-struct --replace-placeholder` replaces only an empty structure.
+
+## Version porting and library identification
+
+`version-tracking create --source-target <id> --source-session <id>` creates a persistent native
+VT session inside the destination research scope. The returned tracking ID owns the exact saved
+source/destination snapshots. `list`, `matches --tracking <id>` and `markup --tracking <id>
+--source-address <address> --destination-address <address>` retain native correlator/score/markup
+provenance. Exact function bytes and duplicate instruction correlators are selected; instruction
+matching can ignore operands. Ambiguity is retained. Unmatched means no association in these
+selected policies, not proof of no equivalent function. Inputs are limited to 10000 functions;
+correlation has a 60-second monitor budget, match pages have at most 1000 rows.
+
+`decide` explicitly accepts, rejects or resets an association; native one-to-one constraints apply.
+Decisions survive owner replacement. Markup is inspected before ordinary facade edits transfer
+selected changes. No automatic markup application/publication is performed. Context-changed flags
+warn when current programs differ from the VT snapshots. Unknown decisions block further decisions
+on that object until reconciliation; the same request ID never blindly repeats a native effect.
+
+`libraries build-fid --library <name> --library-version <version> --output-directory <new-directory>`
+creates a genuine native FID database. `libraries fid-query --database <file.fidb> --function <entry>
+--threshold 1` reports native scores, library/version/variant, database digest and no-match semantics.
+`build-bsim --library <name> --output-directory <new-directory>` creates embedded native BSim/H2;
+`bsim-query --database <database.mv.db> --function <entry> --similarity 0.9` reports signature version,
+similarity and significance. Required SDK components are supplied by the pinned Ghidra install;
+there is no external database service to provision for these local workflows. Inputs are bounded to
+1000 functions, output is bounded, and scores are not calibrated probabilities. Query databases
+are consumed into private immutable storage; the caller's file is unchanged.
+
+## Live target and retained trace
+
+`debugger write-memory --address <dynamic-address> --expect-hex <bytes> --bytes-hex <bytes>`
+and `write-register --register <name> --expect-value <hex> --value <hex>` require a stopped,
+selected live target at its current live time. They refresh from the target before and after the
+write. Preconditions are read-before-write checks, not atomic compare-exchange. Register width
+is exact. These live effects do not enter program publication. A lost write response remains
+uncertain and is never replayed, even when trace bytes subsequently show the requested value.
+The owned copy of Ghidra 12.1.2's Python adapter corrects its SBProcess memory-write call; the
+installed SDK/wheel remains unchanged and runtime fingerprint checks still apply.
+
+`debugger timeline --limit 100` returns snapshot keys/times/schedules and continuation.
+`objects --limit 100 --max-scan 10000` returns persistent object IDs, schema, path and lifespan
+at a selected snap. `object-values --object-id <id> --key <exact-key>` reads one key, optionally
+over at most 1000 snapshot keys. Values preserve address/object-reference types and 64-bit integers;
+unknown Java value kinds are explicit. Object iteration is budgeted, paths replace the owned
+staging root with `@target`, and IDs remain scoped to the selected trace. `schedule --schedule <time>`
+parses/validates native schedules and reports `executed: false`. It does not execute emulation.
+Saved trace queries remain available after disconnect; live execution is never resurrected.