@eyeauras/insight-cli 0.0.0-stage → 0.1.0

package/references/native/InsightSdkTools.java

@@ -0,0 +1,338 @@
+package insight;
+
+import com.google.gson.*;
+import ghidra.app.decompiler.*;
+import ghidra.app.plugin.assembler.Assemblers;
+import ghidra.program.model.address.*;
+import ghidra.program.model.lang.*;
+import ghidra.program.model.listing.*;
+import ghidra.program.model.mem.*;
+import ghidra.program.model.pcode.*;
+import ghidra.program.model.symbol.*;
+import ghidra.program.util.*;
+import ghidra.util.task.*;
+import java.math.BigInteger;
+import java.security.MessageDigest;
+import java.util.*;
+import java.util.concurrent.TimeUnit;
+
+/** Selected typed SDK workflows. Every edit is verified again on an immutable saved Program. */
+public class InsightSdkTools {
+    public static class Rejected extends Exception {
+        public Rejected(Exception cause) {super("SDK transaction rolled back",cause);}
+    }
+    public static String text(JsonObject p, String key) {
+        return p.has(key) && !p.get(key).isJsonNull() ? p.get(key).getAsString() : "";
+    }
+    static int integer(JsonObject p, String key, int fallback, int max) {
+        int n=p.has(key)?p.get(key).getAsInt():fallback;
+        if(n<1||n>max)throw new IllegalArgumentException("Invalid "+key+" bound");
+        return n;
+    }
+    static Address at(Program program, String value) {
+        Address address=program.getAddressFactory().getAddress(value);
+        if(address==null)throw new IllegalArgumentException("Address is not in this program's address spaces");
+        return address;
+    }
+    static byte[] hex(String value) {
+        if(value.isEmpty()||value.length()>8192||!value.matches("(?:[a-fA-F0-9]{2})+"))
+            throw new IllegalArgumentException("Expected 1–4096 complete hex bytes");
+        return HexFormat.of().parseHex(value);
+    }
+    static byte[] bytes(Program program, Address start, int size) throws Exception {
+        byte[] bytes=new byte[size];
+        if(program.getMemory().getBytes(start,bytes)!=size)throw new IllegalStateException("Incomplete memory range");
+        return bytes;
+    }
+    static String hash(Program program, Address start, long size) throws Exception {
+        if(size<1||size>16777216)throw new IllegalArgumentException("Memory verification bound is 16 MiB");
+        MessageDigest hash=MessageDigest.getInstance("SHA-256");
+        for(long offset=0;offset<size;){int count=(int)Math.min(65536,size-offset);hash.update(bytes(program,start.add(offset),count));offset+=count;}
+        return HexFormat.of().formatHex(hash.digest());
+    }
+    static MemoryBlock block(Program program, String name) {
+        // Ghidra's name lookup cache can retain a removed block until transaction completion.
+        MemoryBlock block=Arrays.stream(program.getMemory().getBlocks()).filter(value->value.getName().equals(name)).findFirst().orElse(null);
+        if(block==null)throw new IllegalArgumentException("Memory block does not exist");
+        return block;
+    }
+    static Map<String,Object> blockState(Program program, MemoryBlock b) throws Exception {
+        Map<String,Object> row=new LinkedHashMap<>();
+        row.put("name",b.getName());row.put("start",b.getStart().toString());row.put("end",b.getEnd().toString());
+        row.put("size",b.getSize());row.put("initialized",b.isInitialized());row.put("overlay",b.isOverlay());
+        row.put("read",b.isRead());row.put("write",b.isWrite());row.put("execute",b.isExecute());
+        row.put("sha256",b.isInitialized()?hash(program,b.getStart(),b.getSize()):null);return row;
+    }
+    static void require(boolean condition, String message) {
+        if(!condition)throw new IllegalStateException(message);
+    }
+    static Namespace namespace(Program program,String path) {
+        Namespace current=program.getGlobalNamespace();
+        if(path.isEmpty()||path.equals("Global"))return current;
+        for(String name:path.split("::",-1)){
+            if(name.isEmpty())throw new IllegalArgumentException("Invalid namespace path");
+            current=program.getSymbolTable().getNamespace(name,current);
+            if(current==null)throw new IllegalArgumentException("Namespace does not exist");
+        }
+        return current;
+    }
+    static Map<String,Object> namespaceState(Namespace value) {
+        return Map.of("path",value.getName(true),"name",value.getName(),"kind",value.getSymbol().getSymbolType().toString(),
+            "parent",value.getParentNamespace().isGlobal()?"":value.getParentNamespace().getName(true));
+    }
+    static ExternalLocation external(Program program,JsonObject p) {
+        ExternalLocation value=program.getExternalManager().getUniqueExternalLocation(text(p,"library"),text(p,"label"));
+        if(value==null)throw new IllegalArgumentException("External location is absent or ambiguous");return value;
+    }
+    static Map<String,Object> externalState(ExternalLocation value) {
+        Map<String,Object> row=new LinkedHashMap<>();row.put("library",value.getLibraryName());row.put("label",value.getLabel());
+        row.put("address",value.getAddress()==null?null:value.getAddress().toString());row.put("function",value.isFunction());
+        row.put("symbol_address",value.getExternalSpaceAddress().toString());row.put("source",value.getSource().toString());return row;
+    }
+    static byte[] assembly(Program program,JsonObject p) throws Exception {
+        JsonArray input=p.getAsJsonArray("instructions");
+        if(input==null||input.isEmpty()||input.size()>64)throw new IllegalArgumentException("Assembly requires 1–64 instructions");
+        var assembler=Assemblers.getAssembler(program);Address address=at(program,text(p,"address"));
+        var output=new java.io.ByteArrayOutputStream();
+        for(JsonElement row:input){String line=row.getAsString();if(line.length()>512||line.contains("\n"))throw new IllegalArgumentException("Instruction is not bounded single-line text");
+            byte[] value=assembler.assembleLine(address,line);output.write(value);address=address.add(value.length);}
+        if(output.size()>4096)throw new IllegalArgumentException("Assembly exceeds 4096 bytes");return output.toByteArray();
+    }
+    public static Object read(Program program,String operation,JsonObject p,TaskMonitor monitor) throws Exception {
+        switch(operation) {
+            case "block-state": return blockState(program,block(program,text(p,"name")));
+            case "assembly-preview": {
+                byte[] value=assembly(program,p);
+                return Map.of("address",at(program,text(p,"address")).toString(),"bytes_hex",HexFormat.of().formatHex(value),
+                    "size",value.length,"language",program.getLanguageID().toString(),"context_aware",true);
+            }
+            case "context-read": {
+                Register register=program.getRegister(text(p,"register"));
+                if(register==null)throw new IllegalArgumentException("Unknown processor register");
+                Address start=at(program,text(p,"address")),end=p.has("end_address")?at(program,text(p,"end_address")):start;
+                if(!start.getAddressSpace().equals(end.getAddressSpace())||start.compareTo(end)>0)throw new IllegalArgumentException("Invalid context range");
+                List<Object> rows=new ArrayList<>();var ranges=program.getProgramContext().getRegisterValueAddressRanges(register,start,end);
+                int limit=integer(p,"limit",100,1000);
+                while(ranges.hasNext()&&rows.size()<limit){AddressRange range=ranges.next();var value=program.getProgramContext().getRegisterValue(register,range.getMinAddress());
+                    var explicit=program.getProgramContext().getNonDefaultValue(register,range.getMinAddress());
+                    rows.add(Map.of("start",range.getMinAddress().toString(),"end",range.getMaxAddress().toString(),"known",value.hasValue(),"explicit",explicit!=null&&explicit.hasAnyValue(),
+                        "value","0x"+value.getUnsignedValueIgnoreMask().toString(16),"mask","0x"+value.getValueMask().toString(16)));}
+                return Map.of("register",register.getName(),"bits",register.getBitLength(),"ranges",rows,"complete",!ranges.hasNext());
+            }
+            case "namespace-list": {
+                Namespace parent=namespace(program,text(p,"parent"));var iter=program.getSymbolTable().getSymbols(parent);
+                int limit=integer(p,"limit",100,1000),visited=0,budget=integer(p,"max_scan",10000,200000);List<Object> rows=new ArrayList<>();
+                while(iter.hasNext()&&rows.size()<limit&&visited<budget){monitor.checkCancelled();Symbol symbol=iter.next();visited++;
+                    if(symbol.getSymbolType()==SymbolType.NAMESPACE||symbol.getSymbolType()==SymbolType.CLASS)rows.add(namespaceState((Namespace)symbol.getObject()));}
+                return Map.of("items",rows,"visited",visited,"complete",!iter.hasNext());
+            }
+            case "external-list": {
+                var manager=program.getExternalManager();List<Object> rows=new ArrayList<>();int limit=integer(p,"limit",100,1000);
+                String library=text(p,"library");
+                if(library.isEmpty()){String[] names=manager.getExternalLibraryNames();for(int i=0;i<Math.min(names.length,limit);i++){
+                    Map<String,Object> row=new LinkedHashMap<>();row.put("name",names[i]);row.put("path",manager.getExternalLibraryPath(names[i]));rows.add(row);}
+                    return Map.of("items",rows,"complete",names.length<=limit);}
+                var iter=manager.getExternalLocations(library);while(iter.hasNext()&&rows.size()<limit){monitor.checkCancelled();rows.add(externalState(iter.next()));}
+                return Map.of("items",rows,"complete",!iter.hasNext());
+            }
+            case "decompiler-ir": return decompile(program,p,monitor);
+            case "type-layout": return InsightSdkTypes.layout(program.getDataTypeManager().getDataType(text(p,"path")));
+            default: throw new IllegalArgumentException("Unknown typed SDK read");
+        }
+    }
+    public static Object mutate(Program program,String operation,JsonObject p,TaskMonitor monitor) throws Exception {
+        int transaction=program.startTransaction("insight "+operation);boolean committed=false,closed=false;
+        try {
+            var memory=program.getMemory();var symbols=program.getSymbolTable();var externals=program.getExternalManager();
+            switch(operation) {
+                case "type-structure": case "type-settings": case "type-archive-import":InsightSdkTypes.edit(program,operation,p,monitor);break;
+                case "patch-bytes": case "assemble": {
+                    Address start=at(program,text(p,"address"));byte[] expected=hex(text(p,"expect_hex"));
+                    byte[] desired=operation.equals("assemble")?assembly(program,p):hex(text(p,"bytes_hex"));
+                    if(expected.length!=desired.length)throw new IllegalArgumentException("Expected and replacement lengths must match");
+                    require(Arrays.equals(bytes(program,start,expected.length),expected),"Memory byte precondition changed");
+                    program.getListing().clearCodeUnits(start,start.add(desired.length-1),false,monitor);memory.setBytes(start,desired);break;
+                }
+                case "split-block": {
+                    MemoryBlock original=block(program,text(p,"name"));require(hash(program,original.getStart(),original.getSize()).equals(text(p,"expect_sha256")),"Block content precondition changed");
+                    require(original.getStart().equals(at(program,text(p,"expect_start")))&&original.getSize()==p.get("expect_size").getAsLong(),"Block layout precondition changed");
+                    Address split=at(program,text(p,"split_address"));memory.split(original,split);memory.getBlock(split).setName(text(p,"new_name"));break;
+                }
+                case "move-block": {
+                    MemoryBlock original=block(program,text(p,"name"));require(hash(program,original.getStart(),original.getSize()).equals(text(p,"expect_sha256")),"Block content precondition changed");
+                    require(original.getStart().equals(at(program,text(p,"expect_start")))&&original.getSize()==p.get("expect_size").getAsLong(),"Block layout precondition changed");
+                    memory.moveBlock(original,at(program,text(p,"address")),monitor);break;
+                }
+                case "join-blocks": {
+                    MemoryBlock first=block(program,text(p,"name")),second=block(program,text(p,"second_name"));
+                    require(first.getSize()==p.get("expect_size").getAsLong()&&second.getSize()==p.get("second_size").getAsLong(),"Block sizes changed");
+                    require(first.getEnd().next().equals(second.getStart()),"Blocks must be adjacent in the declared order");
+                    require(hash(program,first.getStart(),first.getSize()).equals(text(p,"expect_sha256"))&&hash(program,second.getStart(),second.getSize()).equals(text(p,"second_sha256")),"Block contents changed");
+                    memory.join(first,second);break;
+                }
+                case "context-set": {
+                    Register register=program.getRegister(text(p,"register"));if(register==null)throw new IllegalArgumentException("Unknown processor register");
+                    Address start=at(program,text(p,"address")),end=at(program,text(p,"end_address"));
+                    program.getProgramContext().setValue(register,start,end,new BigInteger(text(p,"value").replaceFirst("^0x",""),16));break;
+                }
+                case "context-clear": {
+                    Register register=program.getRegister(text(p,"register"));if(register==null)throw new IllegalArgumentException("Unknown processor register");
+                    program.getProgramContext().remove(at(program,text(p,"address")),at(program,text(p,"end_address")),register);break;
+                }
+                case "namespace-create": {
+                    Namespace parent=namespace(program,text(p,"parent"));
+                    if(p.has("class")&&p.get("class").getAsBoolean())symbols.createClass(parent,text(p,"name"),SourceType.USER_DEFINED);
+                    else symbols.createNameSpace(parent,text(p,"name"),SourceType.USER_DEFINED);break;
+                }
+                case "namespace-update": {
+                    Namespace value=namespace(program,text(p,"path"));require(!value.isGlobal()&&!value.isExternal()&&!value.getSymbol().getSymbolType().equals(SymbolType.FUNCTION),"Only ordinary namespaces/classes can be edited");
+                    value.getSymbol().setNameAndNamespace(text(p,"new_name"),namespace(program,text(p,"parent")),SourceType.USER_DEFINED);break;
+                }
+                case "namespace-delete": {
+                    Namespace value=namespace(program,text(p,"path"));require(!value.isGlobal()&&!value.isExternal()&&!value.getSymbol().getSymbolType().equals(SymbolType.FUNCTION),"Only ordinary namespaces/classes can be deleted");
+                    require(!symbols.getSymbols(value).hasNext(),"Namespace must be empty");require(value.getSymbol().delete(),"Namespace deletion was refused");break;
+                }
+                case "library-create": externals.addExternalLibraryName(text(p,"name"),SourceType.USER_DEFINED);break;
+                case "library-update": {
+                    require(externals.contains(text(p,"name")),"External library does not exist");
+                    if(p.has("new_name"))externals.updateExternalLibraryName(text(p,"name"),text(p,"new_name"),SourceType.USER_DEFINED);
+                    if(p.has("path"))externals.setExternalPath(p.has("new_name")?text(p,"new_name"):text(p,"name"),text(p,"path"),true);break;
+                }
+                case "library-delete": require(externals.removeExternalLibrary(text(p,"name")),"Library is absent or still contains external locations");break;
+                case "external-create": {
+                    require(externals.contains(text(p,"library")),"Create the explicit external library first");
+                    require(externals.getExternalLocations(text(p,"library"),text(p,"label")).isEmpty(),"External label already exists");
+                    Address address=p.has("address")?at(program,text(p,"address")):null;
+                    if(p.has("function")&&p.get("function").getAsBoolean())externals.addExtFunction(text(p,"library"),text(p,"label"),address,SourceType.USER_DEFINED);
+                    else externals.addExtLocation(text(p,"library"),text(p,"label"),address,SourceType.USER_DEFINED);break;
+                }
+                case "external-update": {
+                    ExternalLocation value=external(program,p);value.setLocation(text(p,"new_label"),p.has("address")?at(program,text(p,"address")):value.getAddress(),SourceType.USER_DEFINED);break;
+                }
+                case "external-delete": {
+                    ExternalLocation value=external(program,p);Address address=value.getExternalSpaceAddress();
+                    require(!program.getReferenceManager().hasReferencesTo(address),"External location has retained references");
+                    if(value.isFunction())program.getFunctionManager().removeFunction(address);
+                    Symbol remaining=symbols.getPrimarySymbol(address);
+                    if(remaining!=null)require(remaining.delete(),"External location deletion was refused");break;
+                }
+                default: throw new IllegalArgumentException("Unknown typed SDK edit");
+            }
+            Object verified=verify(program,operation,p,monitor);committed=true;return Map.of("success",true,"effect",verified);
+        } catch(Exception failure) {
+            // A rejection receipt is emitted only after native rollback returned successfully.
+            closed=true;program.endTransaction(transaction,false);throw new Rejected(failure);
+        } finally {if(!closed)program.endTransaction(transaction,committed);}
+    }
+    public static Object verify(Program program,String operation,JsonObject p,TaskMonitor monitor) throws Exception {
+        switch(operation) {
+            case "type-structure": case "type-settings": case "type-archive-import":return InsightSdkTypes.verify(program,operation,p,monitor);
+            case "patch-bytes": case "assemble": {
+                byte[] desired=operation.equals("assemble")?assembly(program,p):hex(text(p,"bytes_hex"));
+                Address address=at(program,text(p,"address"));require(Arrays.equals(bytes(program,address,desired.length),desired),"Saved replacement bytes differ");
+                return Map.of("verified",true,"address",address.toString(),"bytes_hex",HexFormat.of().formatHex(desired),"size",desired.length);
+            }
+            case "move-block": {
+                MemoryBlock value=block(program,text(p,"name"));require(value.getStart().equals(at(program,text(p,"address")))&&value.getSize()==p.get("expect_size").getAsLong(),"Saved moved layout differs");
+                require(hash(program,value.getStart(),value.getSize()).equals(text(p,"expect_sha256")),"Saved moved bytes differ");return blockState(program,value);
+            }
+            case "split-block": {
+                MemoryBlock first=block(program,text(p,"name")),second=block(program,text(p,"new_name"));
+                require(first.getStart().equals(at(program,text(p,"expect_start")))&&second.getStart().equals(at(program,text(p,"split_address")))&&first.getEnd().next().equals(second.getStart())&&first.getSize()+second.getSize()==p.get("expect_size").getAsLong(),"Saved split layout differs");
+                require(hash(program,first.getStart(),first.getSize()+second.getSize()).equals(text(p,"expect_sha256")),"Saved split bytes differ");
+                return Map.of("first",blockState(program,first),"second",blockState(program,second));
+            }
+            case "join-blocks": {
+                MemoryBlock value=block(program,text(p,"name"));long size=p.get("expect_size").getAsLong(),other=p.get("second_size").getAsLong();
+                require(value.getSize()==size+other&&Arrays.stream(program.getMemory().getBlocks()).noneMatch(item->item.getName().equals(text(p,"second_name"))),"Saved joined layout differs");
+                require(hash(program,value.getStart(),size).equals(text(p,"expect_sha256"))&&hash(program,value.getStart().add(size),other).equals(text(p,"second_sha256")),"Saved joined bytes differ");return blockState(program,value);
+            }
+            case "context-set": case "context-clear": {
+                Register register=program.getRegister(text(p,"register"));Address start=at(program,text(p,"address")),end=at(program,text(p,"end_address"));
+                var context=program.getProgramContext();BigInteger expected=operation.equals("context-clear")?null:new BigInteger(text(p,"value").replaceFirst("^0x",""),16);
+                Address cursor=start;
+                for(int visited=0;cursor.compareTo(end)<=0;visited++){
+                    if(visited>=65536)throw new IllegalArgumentException("Context verification exceeds 65536 bytes");
+                    if(expected==null){var explicit=context.getNonDefaultValue(register,cursor);require(explicit==null||!explicit.hasAnyValue(),"Saved explicit processor context remains");}
+                    else require(Objects.equals(context.getValue(register,cursor,false),expected),"Saved processor context differs");cursor=cursor.next();
+                }
+                return Map.of("verified",true,"register",register.getName(),"start",start.toString(),"end",end.toString());
+            }
+            case "namespace-create": case "namespace-update": {
+                String name=operation.equals("namespace-create")?text(p,"name"):text(p,"new_name"),parent=text(p,"parent");
+                Namespace value=namespace(program,parent.isEmpty()?name:parent+"::"+name);
+                if(operation.equals("namespace-create"))require(value.getSymbol().getSymbolType()==(p.has("class")&&p.get("class").getAsBoolean()?SymbolType.CLASS:SymbolType.NAMESPACE),"Saved namespace kind differs");return namespaceState(value);
+            }
+            case "namespace-delete": {
+                String path=text(p,"path");int i=path.lastIndexOf("::");Namespace parent=namespace(program,i<0?"":path.substring(0,i));
+                require(program.getSymbolTable().getNamespace(i<0?path:path.substring(i+2),parent)==null,"Saved namespace still exists");return Map.of("deleted",true);
+            }
+            case "library-create": case "library-update": {
+                String name=p.has("new_name")?text(p,"new_name"):text(p,"name");var manager=program.getExternalManager();require(manager.contains(name),"Saved library is absent");
+                if(p.has("path"))require(Objects.equals(manager.getExternalLibraryPath(name),text(p,"path")),"Saved library path differs");
+                return Map.of("name",name,"path",Objects.toString(manager.getExternalLibraryPath(name),""));
+            }
+            case "library-delete": require(!program.getExternalManager().contains(text(p,"name")),"Saved library still exists");return Map.of("deleted",true);
+            case "external-create": case "external-update": {
+                String label=p.has("new_label")?text(p,"new_label"):text(p,"label");var value=program.getExternalManager().getUniqueExternalLocation(text(p,"library"),label);
+                require(value!=null,"Saved external location is absent or ambiguous");
+                if(p.has("address"))require(at(program,text(p,"address")).equals(value.getAddress()),"Saved external address differs");
+                if(p.has("function"))require(value.isFunction()==p.get("function").getAsBoolean(),"Saved external kind differs");return externalState(value);
+            }
+            case "external-delete": require(program.getExternalManager().getExternalLocations(text(p,"library"),text(p,"label")).isEmpty(),"Saved external location remains");return Map.of("deleted",true);
+            default:throw new IllegalArgumentException("Unknown saved SDK verification");
+        }
+    }
+    static Map<String,Object> varnode(Varnode value) {
+        return Map.of("space",value.getAddress().getAddressSpace().getName(),"offset","0x"+Long.toUnsignedString(value.getOffset(),16),"size",value.getSize(),"unique_id",value instanceof VarnodeAST ast?ast.getUniqueId():-1);
+    }
+    static Object decompile(Program program,JsonObject p,TaskMonitor monitor) throws Exception {
+        Function function=program.getFunctionManager().getFunctionAt(at(program,text(p,"address")));
+        if(function==null)throw new IllegalArgumentException("No function starts at this address");
+        String style=p.has("simplification")?text(p,"simplification"):"decompile";
+        if(!List.of("decompile","normalize","firstpass","register","paramid").contains(style))throw new IllegalArgumentException("Unknown simplification style");
+        int limit=integer(p,"max_ops",1000,10000),seconds=integer(p,"timeout_seconds",30,120);
+        DecompInterface decompiler=new DecompInterface();
+        try {
+            DecompileOptions options=new DecompileOptions();options.grabFromProgram(program);options.setMaxPayloadMBytes(8);options.setMaxInstructions(200000);
+            if(p.has("options")){JsonObject values=p.getAsJsonObject("options");for(String key:values.keySet()){
+                switch(key){case "eliminate_unreachable":options.setEliminateUnreachable(values.get(key).getAsBoolean());break;
+                    case "respect_read_only":options.setRespectReadOnly(values.get(key).getAsBoolean());break;
+                    case "infer_constant_pointers":options.setInferConstantPointers(values.get(key).getAsBoolean());break;
+                    case "split_structures":options.setSplitStructures(values.get(key).getAsBoolean());break;
+                    case "split_arrays":options.setSplitArrays(values.get(key).getAsBoolean());break;
+                    default:throw new IllegalArgumentException("Unknown decompiler option");}}}
+            decompiler.setOptions(options);decompiler.setSimplificationStyle(style);decompiler.toggleSyntaxTree(true);
+            decompiler.toggleCCode(p.has("c_code")&&p.get("c_code").getAsBoolean());
+            require(decompiler.openProgram(program),"Decompiler could not open the program");
+            DecompileResults result=decompiler.decompileFunction(function,seconds,monitor);
+            if(!result.decompileCompleted())return Map.of("completed",false,"timed_out",result.isTimedOut(),"diagnostic",result.getErrorMessage(),"operations",List.of());
+            HighFunction high=result.getHighFunction();List<Object> rows=new ArrayList<>();var iter=high.getPcodeOps();
+            while(iter.hasNext()&&rows.size()<limit){monitor.checkCancelled();PcodeOpAST op=iter.next();List<Object> inputs=new ArrayList<>();for(Varnode input:op.getInputs())inputs.add(varnode(input));
+                Map<String,Object> row=new LinkedHashMap<>();row.put("opcode",op.getMnemonic());row.put("address",op.getSeqnum().getTarget().toString());row.put("order",op.getSeqnum().getTime());
+                row.put("block",op.getParent().getIndex());row.put("inputs",inputs);row.put("output",op.getOutput()==null?null:varnode(op.getOutput()));rows.add(row);}
+            Map<String,Object> out=new LinkedHashMap<>();out.put("completed",true);out.put("operations",rows);out.put("ir_complete",!iter.hasNext());out.put("simplification",style);
+            out.put("language",program.getLanguageID().toString());out.put("address",function.getEntryPoint().toString());out.put("diagnostic",result.getErrorMessage());
+            if(p.has("c_code")&&p.get("c_code").getAsBoolean()){String c=result.getDecompiledFunction().getC();out.put("c_code",c.substring(0,Math.min(c.length(),131072)));out.put("c_complete",c.length()<=131072);}
+            return out;
+        } finally {decompiler.dispose();}
+    }
+    public static Object compare(Program first,Program second,JsonObject p,TaskMonitor monitor) throws Exception {
+        Map<String,Integer> categories=new LinkedHashMap<>();categories.put("bytes",ProgramDiffFilter.BYTE_DIFFS);categories.put("code_units",ProgramDiffFilter.CODE_UNIT_DIFFS);
+        categories.put("comments",ProgramDiffFilter.COMMENT_DIFFS);categories.put("symbols",ProgramDiffFilter.SYMBOL_DIFFS);categories.put("functions",ProgramDiffFilter.FUNCTION_DIFFS);
+        categories.put("references",ProgramDiffFilter.REFERENCE_DIFFS);categories.put("context",ProgramDiffFilter.PROGRAM_CONTEXT_DIFFS);categories.put("properties",ProgramDiffFilter.USER_DEFINED_DIFFS);
+        JsonArray requested=p.has("categories")?p.getAsJsonArray("categories"):new Gson().toJsonTree(List.of("bytes","comments","symbols","functions")).getAsJsonArray();
+        if(requested.isEmpty()||requested.size()>categories.size())throw new IllegalArgumentException("Select 1–8 diff categories");
+        int limit=integer(p,"max_ranges",100,1000),seconds=integer(p,"timeout_seconds",30,120);List<Object> rows=new ArrayList<>();boolean complete=true;
+        TimeoutTaskMonitor bounded=TimeoutTaskMonitor.timeoutIn(seconds,TimeUnit.SECONDS,monitor);
+        try {
+            ProgramDiff diff=new ProgramDiff(first,second);
+            for(JsonElement item:requested){String category=item.getAsString();Integer filter=categories.get(category);if(filter==null)throw new IllegalArgumentException("Unknown diff category");
+                AddressSetView differences=diff.getDifferences(new ProgramDiffFilter(filter),bounded);List<Object> ranges=new ArrayList<>();var iterator=differences.getAddressRanges();
+                while(iterator.hasNext()&&ranges.size()<limit){AddressRange range=iterator.next();ranges.add(Map.of("start",range.getMinAddress().toString(),"end",range.getMaxAddress().toString(),"length",Long.toUnsignedString(range.getLength())));}
+                boolean categoryComplete=!iterator.hasNext();complete&=categoryComplete;rows.add(Map.of("category",category,"ranges",ranges,"complete",categoryComplete));}
+        } finally {bounded.finished();}
+        return Map.of("algorithm","ghidra.ProgramDiff","categories",rows,"complete",complete,"read_only",true,
+            "memory_only_first",first.getMemory().subtract(second.getMemory()).toString(),"memory_only_second",second.getMemory().subtract(first.getMemory()).toString());
+    }
+}

package/references/native/InsightSdkTypes.java

@@ -0,0 +1,132 @@
+package insight;
+
+import com.google.gson.*;
+import com.xebyte.core.ServiceUtils;
+import ghidra.docking.settings.*;
+import ghidra.program.model.data.*;
+import ghidra.program.model.listing.Program;
+import ghidra.util.task.TaskMonitor;
+import java.nio.file.*;
+import java.util.*;
+import java.math.BigInteger;
+
+/** Native GDT/layout/settings workflows, including bitfields rather than C text substitutes. */
+public class InsightSdkTypes {
+    static String text(JsonObject p,String key){return InsightSdkTools.text(p,key);}
+    static DataType type(Program program,String path){DataType value=program.getDataTypeManager().getDataType(path);
+        if(value==null)throw new IllegalArgumentException("Explicit type path is absent");return value;}
+    static DataType resolve(Program program,DataTypeManager manager,String name)throws Exception{
+        DataType source=program.getDataTypeManager().getDataType(name);
+        if(source==null)source=ServiceUtils.findDataTypeByNameInAllCategories(program.getDataTypeManager(),name);
+        DataType value=source==null?ServiceUtils.resolveDataType(manager,name):manager.resolve(source,DataTypeConflictHandler.DEFAULT_HANDLER);
+        if(value==null)throw new IllegalArgumentException("Field type could not be resolved");return value;
+    }
+    static List<Object> settings(DataType type){List<Object> rows=new ArrayList<>();Settings values=type.getDefaultSettings();
+        for(SettingsDefinition definition:type.getSettingsDefinitions()){
+            Map<String,Object> row=new LinkedHashMap<>();row.put("name",definition.getName());row.put("definition",definition.getClass().getSimpleName());row.put("explicit",definition.hasValue(values));
+            if(definition instanceof EnumSettingsDefinition enumeration){row.put("value",enumeration.getChoice(values));row.put("choices",enumeration.getDisplayChoices(values));}
+            else if(definition instanceof StringSettingsDefinition string)row.put("value",string.getValue(values));
+            else if(definition instanceof BooleanSettingsDefinition bool)row.put("value",bool.getValue(values));
+            else if(definition instanceof NumberSettingsDefinition number)row.put("value",Long.toString(number.getValue(values)));
+            else row.put("value",definition.getValueString(values));rows.add(row);}
+        return rows;
+    }
+    public static Object layout(DataType value){
+        if(value==null)throw new IllegalArgumentException("Explicit type path is absent");
+        Map<String,Object> row=new LinkedHashMap<>();row.put("path",value.getPathName());row.put("size",value.getLength());row.put("alignment",value.getAlignment());row.put("settings",settings(value));
+        var source=value.getSourceArchive();row.put("source_archive",source==null?null:Map.of("id",source.getSourceArchiveID().toString(),"name",source.getName(),"type",source.getArchiveType().toString()));
+        row.put("universal_id",value.getUniversalID()==null?null:value.getUniversalID().toString());
+        if(value instanceof Composite composite){
+            row.put("packing",composite.getPackingType().toString());row.put("packing_value",composite.getExplicitPackingValue());row.put("minimum_alignment",composite.getExplicitMinimumAlignment());
+            List<Object> fields=new ArrayList<>();int total=composite.getNumDefinedComponents();
+            DataTypeComponent[] components=total<=10000?composite.getDefinedComponents():new DataTypeComponent[0];
+            for(DataTypeComponent field:components){if(fields.size()>=256)break;
+                Map<String,Object> item=new LinkedHashMap<>();item.put("name",field.getFieldName());item.put("type",field.getDataType().getPathName());item.put("offset",field.getOffset());item.put("size",field.getLength());item.put("comment",field.getComment());
+                if(field.getDataType() instanceof BitFieldDataType bit){item.put("bit_size",bit.getDeclaredBitSize());item.put("bit_offset",bit.getBitOffset());item.put("base_type",bit.getBaseDataType().getPathName());}fields.add(item);}
+            row.put("fields",fields);row.put("fields_total",total);row.put("fields_complete",fields.size()==total);}
+        return row;
+    }
+    static Structure structure(Program program,DataTypeManager manager,JsonObject p)throws Exception{
+        String path=text(p,"path");int slash=path.lastIndexOf('/');
+        if(slash<0||slash==path.length()-1)throw new IllegalArgumentException("Structure requires an absolute type path");
+        Structure structure=new StructureDataType(new CategoryPath(slash==0?"/":path.substring(0,slash)),path.substring(slash+1),0,manager);
+        int packing=p.has("packing")?p.get("packing").getAsInt():0;
+        if(packing<0)structure.setPackingEnabled(false);else if(packing==0)structure.setToDefaultPacking();else structure.setExplicitPackingValue(packing);
+        int alignment=p.has("alignment")?p.get("alignment").getAsInt():0;
+        if(alignment<0)structure.setToMachineAligned();else if(alignment==0)structure.setToDefaultAligned();else structure.setExplicitMinimumAlignment(alignment);
+        JsonArray fields=p.getAsJsonArray("fields");if(fields==null||fields.isEmpty()||fields.size()>256)throw new IllegalArgumentException("Structure requires 1–256 fields");
+        Set<String> names=new HashSet<>();for(JsonElement element:fields){JsonObject field=element.getAsJsonObject();String name=text(field,"name");
+            if(name.isEmpty()||!names.add(name))throw new IllegalArgumentException("Field names must be nonempty and unique");
+            DataType type=resolve(program,manager,text(field,"type"));String comment=field.has("comment")?text(field,"comment"):null;
+            if(field.has("offset")){
+                if(structure.isPackingEnabled())throw new IllegalArgumentException("Explicit offsets require disabled packing");int offset=field.get("offset").getAsInt();
+                if(offset<0||offset>1048576)throw new IllegalArgumentException("Field offset exceeds layout bound");
+                if(field.has("bit_size")){int width=field.has("byte_width")?field.get("byte_width").getAsInt():type.getLength(),bit=field.has("bit_offset")?field.get("bit_offset").getAsInt():0;
+                    structure.insertBitFieldAt(offset,width,bit,type,field.get("bit_size").getAsInt(),name,comment);}
+                else {if(offset<structure.getLength())throw new IllegalArgumentException("Explicit fields cannot overlap");structure.growStructure(offset-structure.getLength());structure.add(type,name,comment);}
+            }else if(field.has("bit_size"))structure.addBitField(type,field.get("bit_size").getAsInt(),name,comment);
+            else structure.add(type,name,comment);
+        }return structure;
+    }
+    public static void edit(Program program,String operation,JsonObject p,TaskMonitor monitor)throws Exception{
+        switch(operation){
+            case "type-structure": {
+                var manager=program.getDataTypeManager();DataType existing=manager.getDataType(text(p,"path"));
+                if(existing!=null&&(!p.has("replace_placeholder")||!p.get("replace_placeholder").getAsBoolean()||!(existing instanceof Structure s)||s.getNumDefinedComponents()!=0))throw new IllegalArgumentException("Existing type is not an explicitly replaceable empty structure");
+                Structure wanted=structure(program,manager,p);manager.addDataType(wanted,existing==null?DataTypeConflictHandler.DEFAULT_HANDLER:DataTypeConflictHandler.REPLACE_HANDLER);break;
+            }
+            case "type-settings": {
+                DataType type=type(program,text(p,"path"));JsonObject changes=p.getAsJsonObject("settings");if(changes==null||changes.size()>32)throw new IllegalArgumentException("Settings require at most 32 definition names");
+                Map<String,SettingsDefinition> definitions=new HashMap<>();for(var definition:type.getSettingsDefinitions())definitions.put(definition.getName(),definition);
+                for(String name:changes.keySet()){SettingsDefinition definition=definitions.get(name);if(definition==null)throw new IllegalArgumentException("Unknown native setting definition name");JsonElement value=changes.get(name);Settings settings=type.getDefaultSettings();
+                    if(value.isJsonNull())definition.clear(settings);
+                    else if(definition instanceof EnumSettingsDefinition enumeration){if(!value.isJsonPrimitive()||!value.getAsJsonPrimitive().isNumber())throw new IllegalArgumentException("Native enum setting requires an integer choice");int choice=value.getAsBigDecimal().intValueExact();if(choice<0||choice>=enumeration.getDisplayChoices(settings).length)throw new IllegalArgumentException("Setting choice is outside native enumeration");enumeration.setChoice(settings,choice);}
+                    else if(definition instanceof StringSettingsDefinition string){if(!value.isJsonPrimitive()||!value.getAsJsonPrimitive().isString())throw new IllegalArgumentException("Native string setting requires text");string.setValue(settings,value.getAsString());}
+                    else if(definition instanceof BooleanSettingsDefinition bool){if(!value.isJsonPrimitive()||!value.getAsJsonPrimitive().isBoolean())throw new IllegalArgumentException("Native boolean setting requires a Boolean");bool.setValue(settings,value.getAsBoolean());}
+                    else if(definition instanceof NumberSettingsDefinition number){BigInteger n=new BigInteger(value.getAsString());if(n.signum()<0&&!number.allowNegativeValue()||n.compareTo(number.getMaxValue())>0||n.bitLength()>63)throw new IllegalArgumentException("Numeric setting exceeds native bounds");number.setValue(settings,n.longValueExact());}
+                    else throw new IllegalArgumentException("Native setting has no supported typed setter");}
+                break;
+            }
+            case "type-archive-import": {
+                try(FileDataTypeManager archive=FileDataTypeManager.openFileArchive(Path.of(text(p,"input_path")).toFile(),false)){
+                    JsonArray names=p.getAsJsonArray("types");if(names==null||names.isEmpty()||names.size()>256)throw new IllegalArgumentException("Choose 1–256 archive type paths");
+                    var manager=program.getDataTypeManager();for(JsonElement name:names){DataType wanted=archive.getDataType(name.getAsString());if(wanted==null)throw new IllegalArgumentException("Archive type path is absent");
+                        DataType existing=manager.getDataType(name.getAsString());if(existing!=null&&!existing.isEquivalent(wanted))throw new IllegalArgumentException("Existing type conflicts with the selected archive layout");
+                        manager.resolve(wanted,DataTypeConflictHandler.DEFAULT_HANDLER);}
+                }break;
+            }
+            default:throw new IllegalArgumentException("Unknown type workflow");
+        }
+    }
+    public static Object verify(Program program,String operation,JsonObject p,TaskMonitor monitor)throws Exception{
+        switch(operation){
+            case "type-structure": {
+                DataType actual=type(program,text(p,"path"));try(var expected=new StandAloneDataTypeManager("LayoutVerification",program.getDataTypeManager().getDataOrganization())){
+                    int transaction=expected.startTransaction("Build expected layout");try{
+                        Structure wanted=structure(program,expected,p);InsightSdkTools.require(actual instanceof Structure&&actual.isEquivalent(wanted),"Saved structure fields/packing/bitfields differ");
+                        InsightSdkTools.require(actual.getLength()==wanted.getLength()&&actual.getAlignment()==wanted.getAlignment(),"Saved structure size/alignment differs");return layout(actual);
+                    }finally{expected.endTransaction(transaction,false);}}
+            }
+            case "type-settings": {
+                DataType actual=type(program,text(p,"path"));JsonObject changes=p.getAsJsonObject("settings");Map<String,SettingsDefinition> definitions=new HashMap<>();for(var definition:actual.getSettingsDefinitions())definitions.put(definition.getName(),definition);
+                Settings settings=actual.getDefaultSettings();for(String name:changes.keySet()){SettingsDefinition definition=definitions.get(name);InsightSdkTools.require(definition!=null,"Saved setting definition disappeared");JsonElement expected=changes.get(name);
+                    if(expected.isJsonNull())InsightSdkTools.require(!definition.hasValue(settings),"Saved explicit setting remains");
+                    else if(definition instanceof EnumSettingsDefinition enumeration)InsightSdkTools.require(enumeration.getChoice(settings)==expected.getAsInt(),"Saved enum setting differs");
+                    else if(definition instanceof BooleanSettingsDefinition bool)InsightSdkTools.require(bool.getValue(settings)==expected.getAsBoolean(),"Saved boolean setting differs");
+                    else if(definition instanceof StringSettingsDefinition string)InsightSdkTools.require(Objects.equals(string.getValue(settings),expected.getAsString()),"Saved string setting differs");
+                    else if(definition instanceof NumberSettingsDefinition number)InsightSdkTools.require(Long.toString(number.getValue(settings)).equals(expected.getAsString()),"Saved number setting differs");
+                    else throw new IllegalArgumentException("Unsupported saved setting definition");}
+                return layout(actual);
+            }
+            case "type-archive-import": {
+                try(FileDataTypeManager archive=FileDataTypeManager.openFileArchive(Path.of(text(p,"input_path")).toFile(),false)){
+                    List<Object> rows=new ArrayList<>();for(JsonElement name:p.getAsJsonArray("types")){DataType wanted=archive.getDataType(name.getAsString()),actual=type(program,name.getAsString());
+                        InsightSdkTools.require(wanted!=null&&actual.isEquivalent(wanted),"Saved archive layout differs");
+                        InsightSdkTools.require(actual.getSourceArchive()!=null&&actual.getSourceArchive().getSourceArchiveID().equals(archive.getUniversalID()),"Saved archive source identity differs");rows.add(layout(actual));}
+                    return Map.of("archive_id",archive.getUniversalID().toString(),"types",rows);
+                }
+            }
+            default:throw new IllegalArgumentException("Unknown saved type workflow");
+        }
+    }
+}

package/references/native/InsightServerAdministration.java

@@ -0,0 +1,82 @@
+import com.google.gson.*;
+import com.xebyte.headless.GhidraServerManager;
+import ghidra.GhidraApplicationLayout;
+import ghidra.framework.Application;
+import ghidra.framework.HeadlessGhidraApplicationConfiguration;
+import ghidra.framework.client.RepositoryAdapter;
+import ghidra.framework.remote.RepositoryItem;
+import ghidra.framework.remote.User;
+import java.nio.file.*;
+import java.util.*;
+
+/** Explicit repository administration with server-side authority and independent effect readback. */
+class InsightServerAdministration {
+  static String string(JsonObject value,String name){return value.has(name)?value.get(name).getAsString():"";}
+  static String parent(String path){int i=path.lastIndexOf('/');return i>0?path.substring(0,i):"/";}
+  static String leaf(String path){return path.substring(path.lastIndexOf('/')+1);}
+  // RepositoryItem.getPathName() prepends another slash even when its parent is root.
+  static String canonicalPath(RepositoryItem item){return (item.getParentPath().equals("/")?"":item.getParentPath())+"/"+item.getName();}
+  static Map<String,Object> file(RepositoryItem item){return Map.of("name",item.getName(),"path",canonicalPath(item),"type",item.getContentType(),"version",item.getVersion());}
+  static void admin(RepositoryAdapter repo)throws Exception{if(!repo.getUser().isAdmin())throw new SecurityException("Repository administration requires actual admin permission");}
+  static List<RepositoryItem> files(RepositoryAdapter repo,String at)throws Exception{
+    List<RepositoryItem> out=new ArrayList<>();RepositoryItem exact=at.equals("/")?null:repo.getItem(parent(at),leaf(at));
+    if(exact!=null){out.add(exact);return out;}
+    var pending=new ArrayDeque<String>();pending.add(at);int folders=0;
+    while(!pending.isEmpty()){if(++folders>10000)throw new IllegalArgumentException("Repository walk exceeds 10000 folders");String folder=pending.remove();
+      var items=repo.getItemList(folder);if(items!=null)Collections.addAll(out,items);
+      if(out.size()>10000)throw new IllegalArgumentException("Repository walk exceeds 10000 files");
+      var children=repo.getSubfolderList(folder);if(children!=null)for(String child:children)pending.add((folder.equals("/")?"":folder)+"/"+child);}
+    return out;
+  }
+  public static void main(String[] args){var output=System.out;System.setOut(System.err);
+    try{
+      if(args.length!=1)throw new IllegalArgumentException();String encoded=Files.readString(Path.of(args[0]));if(encoded.length()>65536)throw new IllegalArgumentException();
+      JsonObject request=JsonParser.parseString(encoded).getAsJsonObject();String operation=string(request,"operation"),name=string(request,"repository"),path=string(request,"path");
+      Application.initializeApplication(new GhidraApplicationLayout(),new HeadlessGhidraApplicationConfiguration());
+      var manager=new GhidraServerManager();manager.connect();var server=manager.server();if(server==null||!server.isConnected())throw new SecurityException("Server connection missing");
+      Map<String,Object> result=new LinkedHashMap<>();
+      try{
+        if(operation.equals("repositories")){var names=server.getRepositoryNames();result.put("repositories",Arrays.asList(names));result.put("count",names.length);}
+        else if(operation.equals("users")){var users=server.getAllUsers();result.put("users",Arrays.stream(users).map(user->Map.of("name",user)).toList());result.put("count",users.length);}
+        else if(operation.equals("create_repository")){
+          server.createRepository(name).connect();if(!Arrays.asList(server.getRepositoryNames()).contains(name))throw new IllegalStateException("Created repository missing");
+          result.put("state","created");result.put("repository",name);
+        }else{
+          var repo=server.getRepository(name);repo.connect();try{
+            result.put("repository",name);
+            if(operation.equals("files")){var folders=repo.getSubfolderList(path);var items=repo.getItemList(path);
+              result.put("path",path);result.put("folders",folders==null?List.of():Arrays.asList(folders));result.put("files",items==null?List.of():Arrays.stream(items).map(InsightServerAdministration::file).toList());}
+            else if(operation.equals("file")){var item=repo.getItem(parent(path),leaf(path));if(item==null)throw new IllegalArgumentException("Repository file missing");result.put("file",file(item));}
+            else if(operation.equals("permissions")){result.put("users",Arrays.stream(repo.getUserList()).map(user->Map.of("name",user.getName(),"access",user.getPermissionType())).toList());result.put("anonymous",repo.anonymousAccessAllowed());}
+            else if(operation.equals("set_permissions")){
+              admin(repo);String user=string(request,"user");int level=request.get("access").getAsInt();if(level<0||level>2)throw new IllegalArgumentException();
+              var before=new LinkedHashMap<String,Integer>();for(var item:repo.getUserList())before.put(item.getName(),item.getPermissionType());
+              boolean anonymous=repo.anonymousAccessAllowed();before.put(user,level);repo.setUserList(before.entrySet().stream().map(item->new User(item.getKey(),item.getValue())).toArray(User[]::new),anonymous);
+              var after=new LinkedHashMap<String,Integer>();for(var item:repo.getUserList())after.put(item.getName(),item.getPermissionType());
+              if(!before.equals(after)||repo.anonymousAccessAllowed()!=anonymous)throw new IllegalStateException("Repository ACL readback mismatch");
+              result.put("state","applied");result.put("users",after);result.put("anonymous",anonymous);
+            }else if(operation.equals("history")){var versions=repo.getVersions(parent(path),leaf(path));
+              result.put("path",path);result.put("versions",Arrays.stream(versions).map(version->Map.of("version",version.getVersion(),"user",version.getUser(),"time",version.getCreateTime(),"comment",Objects.toString(version.getComment(),""))).toList());}
+            else if(Set.of("checkouts","terminate_checkout","terminate_all_checkouts").contains(operation)){
+              boolean changing=!operation.equals("checkouts");if(changing)admin(repo);List<Object> rows=new ArrayList<>();int terminated=0;
+              var selected=files(repo,path);
+              if(changing)for(var item:selected){String itemPath=canonicalPath(item);
+                if(request.has("protected_repository")&&name.equals(string(request,"protected_repository"))&&itemPath.matches("/t_[a-f0-9-]+\\.bin"))throw new SecurityException("Facade publication checkout is protected");
+                if(repo.isCheckinActive(parent(itemPath),leaf(itemPath)))throw new IllegalStateException("File has an active check-in");}
+              for(var item:selected){String itemPath=canonicalPath(item);
+                var statuses=repo.getCheckouts(parent(itemPath),leaf(itemPath));if(statuses==null)continue;
+                for(var checkout:statuses){String id=Long.toString(checkout.getCheckoutId());
+                  if(changing){if(operation.equals("terminate_checkout")&&request.has("checkout_id")&&!id.equals(string(request,"checkout_id")))continue;
+                    repo.terminateCheckout(parent(itemPath),leaf(itemPath),checkout.getCheckoutId(),false);
+                    if(repo.getCheckout(parent(itemPath),leaf(itemPath),checkout.getCheckoutId())!=null)throw new IllegalStateException("Checkout remains after termination");terminated++;}
+                  else rows.add(Map.of("path",itemPath,"id",id,"user",checkout.getUser(),"version",checkout.getCheckoutVersion(),"type",checkout.getCheckoutType().toString()));}
+              }
+              result.put(changing?"terminated":"checkouts",changing?terminated:rows);result.put("path",path);
+            }else throw new IllegalArgumentException("Unsupported server administration operation");
+          }finally{repo.disconnect();}
+        }
+      }finally{server.disconnect();}
+      output.println(new GsonBuilder().serializeNulls().create().toJson(result));System.exit(0);
+    }catch(Throwable failure){failure.printStackTrace(System.err);output.println("{\"error\":\"server_administration_not_verified\"}");System.exit(1);}
+  }
+}