feat(introspection): v26.4-Alpha.4 - JVM introspection API (ThreadInsight/ClassStats/HeapSummary/GcSummary/CompilationSummary + JvmInsight facade over MXBeans; 9 tests, 526 total)

Author: StarsailsClover

README.md

@@ -1,7 +1,7 @@
 # Aprism
 
 > A cross-platform, cross-edition, cross-version Minecraft mod loader and injector compatible with JE/BE.
-> Author: BlockConnect@StarsailsClover | Version: v26.4-Alpha.3 (Phase0 internal)
+> Author: BlockConnect@StarsailsClover | Version: v26.4-Alpha.4 (Phase0 internal)
 
 Aprism Loader is a unified mod loading framework that supports JE Fabric, Forge, NeoForge, Quilt and LiteLoader modpacks through Aprism Extensions (.aep, provided by the AprismRefract sub-project), brings a Fabric-like mod loader ecosystem to Bedrock Edition (BE) via native injection, and provides rapid JE-to-BE mod conversion tooling. JE Aprism Native is a modern, JVM-based foundation that forces unified interfaces with a monotonic version contract (only increases, never decreases). The Aprism core itself is native-only: loader support lives outside the core behind the LoaderEntrypointHandler SPI.
 

aprism-api/src/main/java/com/aprism/api/introspection/ClassStats.java

@@ -0,0 +1,14 @@
+package com.aprism.api.introspection;
+
+/**
+ * A snapshot of class-loading statistics (v26.4-Alpha.4, JVM
+ * introspection API).
+ *
+ * @param loadedClassCount classes currently loaded
+ * @param unloadedClassCount classes unloaded since startup
+ * @param totalLoadedClassCount classes loaded since startup
+ * @author BlockConnect@StarsailsClover
+ */
+public record ClassStats(long loadedClassCount, long unloadedClassCount,
+                         long totalLoadedClassCount) {
+}

aprism-api/src/main/java/com/aprism/api/introspection/CompilationSummary.java

@@ -0,0 +1,16 @@
+package com.aprism.api.introspection;
+
+/**
+ * A snapshot of the JIT compiler state (v26.4-Alpha.4, JVM introspection
+ * API).
+ *
+ * @param compilerName the JIT compiler name ({@code null} when no
+ *                     compiler is available)
+ * @param totalCompileTimeMs approximate accumulated compilation time in
+ *                           milliseconds ({@code -1} if unsupported)
+ * @param jitAvailable whether a JIT compiler is present in this VM
+ * @author BlockConnect@StarsailsClover
+ */
+public record CompilationSummary(String compilerName, long totalCompileTimeMs,
+                                 boolean jitAvailable) {
+}

aprism-api/src/main/java/com/aprism/api/introspection/GcSummary.java

@@ -0,0 +1,24 @@
+package com.aprism.api.introspection;
+
+/**
+ * A snapshot of one garbage collector's activity (v26.4-Alpha.4, JVM
+ * introspection API).
+ *
+ * @param name the collector name
+ * @param collectionCount the number of collections performed ({@code -1}
+ *                        if undefined)
+ * @param collectionTimeMs approximate accumulated collection time in
+ *                         milliseconds ({@code -1} if undefined)
+ * @author BlockConnect@StarsailsClover
+ */
+public record GcSummary(String name, long collectionCount, long collectionTimeMs) {
+
+    /**
+     * Canonical compact constructor: validates the name.
+     */
+    public GcSummary {
+        if (name == null || name.isBlank()) {
+            throw new IllegalArgumentException("collector name must be non-blank");
+        }
+    }
+}

aprism-api/src/main/java/com/aprism/api/introspection/HeapSummary.java

@@ -0,0 +1,15 @@
+package com.aprism.api.introspection;
+
+/**
+ * A snapshot of heap and non-heap memory usage (v26.4-Alpha.4, JVM
+ * introspection API). All values are in bytes; {@code -1} means the value
+ * is undefined for this VM.
+ *
+ * @param heapUsed heap bytes currently used
+ * @param heapCommitted heap bytes committed
+ * @param heapMax maximum heap bytes ({@code -1} if undefined)
+ * @param nonHeapUsed non-heap bytes currently used
+ * @author BlockConnect@StarsailsClover
+ */
+public record HeapSummary(long heapUsed, long heapCommitted, long heapMax, long nonHeapUsed) {
+}

aprism-api/src/main/java/com/aprism/api/introspection/JvmInsight.java

@@ -0,0 +1,61 @@
+package com.aprism.api.introspection;
+
+import java.util.List;
+
+/**
+ * JVM introspection surface (v26.4-Alpha.4): a typed, stable view over
+ * thread stacks, class statistics, heap usage, GC activity, JIT state and
+ * VM identity. This is the loader-level foundation the AprismateAgent
+ * performance work builds on; it intentionally reads through
+ * {@code ManagementFactory} MXBeans so it works on any compliant JVM
+ * (including AprismJDK, where deeper seams may later replace it).
+ *
+ * @author BlockConnect@StarsailsClover
+ */
+public interface JvmInsight {
+
+    /**
+     * @return insights for all live threads at this instant
+     */
+    List<ThreadInsight> threads();
+
+    /**
+     * @return current class-loading statistics
+     */
+    ClassStats classStats();
+
+    /**
+     * @return current heap and non-heap usage
+     */
+    HeapSummary heap();
+
+    /**
+     * @return activity snapshots of all registered garbage collectors
+     */
+    List<GcSummary> gcCollectors();
+
+    /**
+     * @return the JIT compiler state
+     */
+    CompilationSummary compilation();
+
+    /**
+     * @return VM uptime in milliseconds
+     */
+    long uptimeMs();
+
+    /**
+     * @return the VM name (e.g. {@code OpenJDK 64-Bit Server VM})
+     */
+    String vmName();
+
+    /**
+     * @return the VM vendor
+     */
+    String vmVendor();
+
+    /**
+     * @return the Java runtime version
+     */
+    String javaVersion();
+}

aprism-api/src/main/java/com/aprism/api/introspection/ThreadInsight.java

@@ -0,0 +1,32 @@
+package com.aprism.api.introspection;
+
+import java.util.List;
+
+/**
+ * A snapshot of a single live thread (v26.4-Alpha.4, JVM introspection
+ * API). Provides the loader-level with a typed view of thread state
+ * without JMX reflection.
+ *
+ * @param threadId the unique thread id
+ * @param name the thread name
+ * @param state the thread state name (e.g. {@code RUNNABLE}, {@code WAITING})
+ * @param stackDepth the current stack depth
+ * @param topFrames the topmost stack frame descriptions (may be empty)
+ * @author BlockConnect@StarsailsClover
+ */
+public record ThreadInsight(long threadId, String name, String state, int stackDepth,
+                            List<String> topFrames) {
+
+    /**
+     * Canonical compact constructor: defensive copies.
+     */
+    public ThreadInsight {
+        if (name == null || name.isBlank()) {
+            throw new IllegalArgumentException("thread name must be non-blank");
+        }
+        if (state == null) {
+            throw new IllegalArgumentException("thread state must be non-null");
+        }
+        topFrames = topFrames == null ? List.of() : List.copyOf(topFrames);
+    }
+}

aprism-loader-core/src/main/java/com/aprism/loader/AprismRuntime.java

@@ -49,6 +49,8 @@
 import com.aprism.loader.networking.NetworkingRegistry;
 import com.aprism.loader.rendering.RenderingRegistry;
 import com.aprism.loader.registry.GameRegistries;
+import com.aprism.api.introspection.JvmInsight;
+import com.aprism.loader.introspection.JvmInsightImpl;
 import com.aprism.loader.settings.SettingsRegistry;
 import com.aprism.loader.modmenu.ModListEntry;
 import com.aprism.loader.modmenu.ModListRegistry;
@@ -116,6 +118,8 @@ public final class AprismRuntime {
     private final ModListRegistry modListRegistry = new ModListRegistry();
     /** Per-mod settings registry (v26.2-Alpha.3, goal #7 part 2). */
     private final SettingsRegistry settingsRegistry = new SettingsRegistry();
+    /** JVM introspection API (v26.4-Alpha.4). */
+    private final JvmInsightImpl jvmInsight = new JvmInsightImpl();
     /** Game-event dispatcher (v26.3-Alpha.1, QA0 gap #1). */
     private GameEventDispatcher gameEventDispatcher;
     /** Typed game-content registries (v26.3-Alpha.2, QA0 gap #2). */
@@ -465,6 +469,14 @@ public SettingsRegistry getSettings() {
         return settingsRegistry;
     }
 
+    /**
+     * @return the JVM introspection surface (v26.4-Alpha.4): threads,
+     *         class stats, heap, GC, JIT and VM identity
+     */
+    public JvmInsight getJvmInsight() {
+        return jvmInsight;
+    }
+
     /**
      * Rebuilds the mod list registry from the current runtime state
      * (v26.2-Alpha.2, goal #7). Every loaded extension and mod contributes a

aprism-loader-core/src/main/java/com/aprism/loader/introspection/JvmInsightImpl.java

@@ -0,0 +1,114 @@
+package com.aprism.loader.introspection;
+
+import com.aprism.api.introspection.ClassStats;
+import com.aprism.api.introspection.CompilationSummary;
+import com.aprism.api.introspection.GcSummary;
+import com.aprism.api.introspection.HeapSummary;
+import com.aprism.api.introspection.JvmInsight;
+import com.aprism.api.introspection.ThreadInsight;
+
+import java.lang.management.ClassLoadingMXBean;
+import java.lang.management.CompilationMXBean;
+import java.lang.management.GarbageCollectorMXBean;
+import java.lang.management.ManagementFactory;
+import java.lang.management.MemoryMXBean;
+import java.lang.management.MemoryUsage;
+import java.lang.management.RuntimeMXBean;
+import java.lang.management.ThreadInfo;
+import java.lang.management.ThreadMXBean;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Implementation of {@link JvmInsight} over the standard
+ * {@code ManagementFactory} MXBeans (v26.4-Alpha.4). Works on any
+ * compliant JVM; on AprismJDK deeper seams may replace individual
+ * methods later without changing this contract.
+ *
+ * @author BlockConnect@StarsailsClover
+ */
+public final class JvmInsightImpl implements JvmInsight {
+
+    /** Maximum number of stack frames captured per thread. */
+    private static final int MAX_FRAMES = 16;
+
+    @Override
+    public List<ThreadInsight> threads() {
+        ThreadMXBean threadBean = ManagementFactory.getThreadMXBean();
+        ThreadInfo[] infos = threadBean.dumpAllThreads(false, false);
+        List<ThreadInsight> result = new ArrayList<>(infos.length);
+        for (ThreadInfo info : infos) {
+            if (info == null) {
+                continue;
+            }
+            StackTraceElement[] stack = info.getStackTrace();
+            List<String> frames = new ArrayList<>();
+            int limit = Math.min(stack.length, MAX_FRAMES);
+            for (int i = 0; i < limit; i++) {
+                frames.add(stack[i].toString());
+            }
+            result.add(new ThreadInsight(info.getThreadId(), info.getThreadName(),
+                    info.getThreadState().name(), stack.length, frames));
+        }
+        return result;
+    }
+
+    @Override
+    public ClassStats classStats() {
+        ClassLoadingMXBean bean = ManagementFactory.getClassLoadingMXBean();
+        return new ClassStats(bean.getLoadedClassCount(), bean.getUnloadedClassCount(),
+                bean.getTotalLoadedClassCount());
+    }
+
+    @Override
+    public HeapSummary heap() {
+        MemoryMXBean bean = ManagementFactory.getMemoryMXBean();
+        MemoryUsage heapUsage = bean.getHeapMemoryUsage();
+        MemoryUsage nonHeapUsage = bean.getNonHeapMemoryUsage();
+        return new HeapSummary(heapUsage.getUsed(), heapUsage.getCommitted(),
+                heapUsage.getMax(), nonHeapUsage.getUsed());
+    }
+
+    @Override
+    public List<GcSummary> gcCollectors() {
+        List<GarbageCollectorMXBean> beans = ManagementFactory.getGarbageCollectorMXBeans();
+        List<GcSummary> result = new ArrayList<>(beans.size());
+        for (GarbageCollectorMXBean bean : beans) {
+            result.add(new GcSummary(bean.getName(), bean.getCollectionCount(),
+                    bean.getCollectionTime()));
+        }
+        return result;
+    }
+
+    @Override
+    public CompilationSummary compilation() {
+        CompilationMXBean bean = ManagementFactory.getCompilationMXBean();
+        if (bean == null) {
+            return new CompilationSummary(null, -1, false);
+        }
+        long time = bean.isCompilationTimeMonitoringSupported()
+                ? bean.getTotalCompilationTime() : -1;
+        return new CompilationSummary(bean.getName(), time, true);
+    }
+
+    @Override
+    public long uptimeMs() {
+        RuntimeMXBean bean = ManagementFactory.getRuntimeMXBean();
+        return bean.getUptime();
+    }
+
+    @Override
+    public String vmName() {
+        return ManagementFactory.getRuntimeMXBean().getVmName();
+    }
+
+    @Override
+    public String vmVendor() {
+        return ManagementFactory.getRuntimeMXBean().getVmVendor();
+    }
+
+    @Override
+    public String javaVersion() {
+        return System.getProperty("java.version");
+    }
+}