feat(neoforge): v26.7-Alpha.4 - E2E hardening round with real JEI mod

Real-game E2E against JEI 30.25.0.177 on MC 26.2 via mdl drove these fixes:

Diagnosability:
- Handler logs the FULL root cause chain on construct failure (was
  toString-only, hiding NoClassDefFoundError causes)

New shims (constructor-chain driven):
- ModLoadingContext (get(), getActiveContainer(), setActiveModId)
- ModContainer stub with registerConfig(Type, IConfigSpec)
- IConfigSpec marker interface
- ModConfig abstract class with Type enum
- ModConfigSpec full family: ConfigValue<T>/BooleanValue/IntValue/
  LongValue/DoubleValue/EnumValue implements Supplier; Builder.define*
  returns typed holders seeded with defaults
- IEventBus.addListener(boolean,...) and addListener(EventPriority,
  boolean,...) default overloads (linkage-compatible with mods compiled
  against real NeoForge)
- Dist.isClient()/isServer()
- IModBusEvent marker; FMLLifecycleEvent implements it
- RegisterPayloadHandlersEvent, OnDatapackSyncEvent event classes
- ModList facade (isLoaded/getLoadedMods/getAllScanData)
- FMLPaths (GAMEDIR/CONFIGDIR/MODDIR resolution), FMLLoader stubs
- neoforgespi ModFileScanData/AnnotationData interfaces

JEI 30.x progression under Aprism:
- v26.6: failed at CLASS LOAD (NoClassDefFoundError: api/distmarker/Dist)
- v26.7-Alpha.4: full classload OK, constructor executes through config
  registration and network event subscription, stops at JEI-internal
  'plugins must not be empty' (requires real annotation-scan of mod jars,
  i.e., Aprism known-issue #4 scope, not a shim gap)

Build green, 11 tests pass.

Author: StarsailsClover

src/main/java/com/aprism/refract/neoforge/NeoForgeEntrypointBridge.java

@@ -109,8 +109,12 @@ private static String scanForMod(Path classFile, String modId) {
 
     /**
      * Instantiates a NeoForge entrypoint class, injecting the given event bus.
-     * Prefers a constructor accepting a single {@link IEventBus} argument; if
-     * absent, falls back to the no-arg constructor.
+     * Tries the known NeoForge constructor conventions in order:
+     * <ol>
+     *   <li>{@code (IEventBus, Dist)} — common on NeoForge 21.x (e.g. JEI)</li>
+     *   <li>{@code (IEventBus)} — classic mod-scoped bus injection</li>
+     *   <li>{@code ()} — no-arg fallback</li>
+     * </ol>
      *
      * @param clazz    the {@code @Mod} entrypoint class
      * @param eventBus the mod-scoped event bus to inject
@@ -119,13 +123,21 @@ private static String scanForMod(Path classFile, String modId) {
     public static Object construct(Class<?> clazz, IEventBus eventBus) {
         try {
             try {
-                var ctor = clazz.getDeclaredConstructor(IEventBus.class);
+                var ctor = clazz.getDeclaredConstructor(IEventBus.class,
+                        net.neoforged.api.distmarker.Dist.class);
                 ctor.setAccessible(true);
-                return ctor.newInstance(eventBus);
+                return ctor.newInstance(eventBus,
+                        net.neoforged.fml.loading.FMLEnvironment.dist);
             } catch (NoSuchMethodException ignored) {
-                var ctor = clazz.getDeclaredConstructor();
-                ctor.setAccessible(true);
-                return ctor.newInstance();
+                try {
+                    var ctor = clazz.getDeclaredConstructor(IEventBus.class);
+                    ctor.setAccessible(true);
+                    return ctor.newInstance(eventBus);
+                } catch (NoSuchMethodException alsoIgnored) {
+                    var ctor = clazz.getDeclaredConstructor();
+                    ctor.setAccessible(true);
+                    return ctor.newInstance();
+                }
             }
         } catch (ReflectiveOperationException e) {
             Throwable cause = e.getCause() != null ? e.getCause() : e;

src/main/java/com/aprism/refract/neoforge/NeoForgeEntrypointHandler.java

@@ -78,6 +78,13 @@ public boolean isExclusive() {
 
     @Override
     public void invoke(LoadedModContainer container, AprismPhase phase) {
+        // Feed the ModList shim so ModList.get().isLoaded(id) answers for
+        // inter-mod presence checks (v26.7-Alpha.4).
+        net.neoforged.fml.ModList.setLoadedMods(java.util.stream.Stream.concat(
+                java.util.Arrays.stream(net.neoforged.fml.ModList.get().getLoadedMods().toArray(new String[0])),
+                java.util.stream.Stream.of(container.getId()))
+                .distinct()
+                .toList());
         switch (phase) {
             case INIT -> initOrFireLifecycleEvent(container, new FMLCommonSetupEvent());
             case CLIENT -> fireLifecycleEvent(container, new FMLClientSetupEvent());
@@ -106,6 +113,9 @@ private void initOrFireLifecycleEvent(LoadedModContainer container, Object lifec
                 return;
             }
             try {
+                // ModLoadingContext.getActiveContainer() must answer THIS mod
+                // while its constructor runs (v26.7-Alpha.4).
+                net.neoforged.fml.ModLoadingContext.setActiveModId(container.getId());
                 Class<?> clazz = Class.forName(modClasses.get(0), true,
                         getClass().getClassLoader());
                 NeoForgeEventBus bus = new NeoForgeEventBus();
@@ -117,8 +127,16 @@ private void initOrFireLifecycleEvent(LoadedModContainer container, Object lifec
                 throw new RuntimeException("Failed to load NeoForge entrypoint for "
                         + container.getId(), e);
             } catch (RuntimeException e) {
+                // Log the full cause chain (v26.7-Alpha.4): shim gaps surface
+                // as NoClassDefFoundError deep in the cause tree; printing only
+                // toString() hid the missing class name.
+                Throwable cause = e;
+                while (cause.getCause() != null && cause.getCause() != cause) {
+                    cause = cause.getCause();
+                }
                 LOG.warning("NeoForge mod " + container.getId()
-                        + " failed to construct during INIT: " + e);
+                        + " failed to construct during INIT: " + e
+                        + " | root cause: " + cause);
             }
         } else {
             fireLifecycleEvent(container, lifecycleEvent);

src/main/java/net/neoforged/api/distmarker/Dist.java

@@ -1,14 +1,27 @@
 package net.neoforged.api.distmarker;
 
 /**
- * NeoForge API shim: distribution side enum. Many NeoForge mods reference
- * {@code Dist.CLIENT} or {@code Dist.DEDICATED_SERVER} in {@code @OnlyIn}
- * annotations and conditional logic. This shim provides the enum so that
- * genuine NeoForge mods can be loaded without the real NeoForge runtime.
+ * NeoForge API shim: distribution side enum with side predicates. Many
+ * NeoForge mods reference {@code Dist.CLIENT} / {@code Dist.DEDICATED_SERVER}
+ * and call {@link #isClient()} / {@link #isServer()} in conditional logic.
  *
  * @author BlockConnect@StarsailsClover
  */
 public enum Dist {
     CLIENT,
-    DEDICATED_SERVER
+    DEDICATED_SERVER;
+
+    /**
+     * @return true if this is the client distribution
+     */
+    public boolean isClient() {
+        return this == CLIENT;
+    }
+
+    /**
+     * @return true if this is the dedicated server distribution
+     */
+    public boolean isServer() {
+        return this == DEDICATED_SERVER;
+    }
 }

src/main/java/net/neoforged/bus/api/IEventBus.java

@@ -13,9 +13,6 @@
  * backs this shim with its own {@code NeoForgeEventBus}, so listeners
  * registered during mod construction are held by the branch extension.
  *
- * <p>Extracted from the Aprism core ({@code aprism-loader-core}) in
- * v26.0-Alpha.2 per the loader-support extraction.
- *
  * @author BlockConnect@StarsailsClover
  */
 public interface IEventBus {
@@ -29,6 +26,37 @@ public interface IEventBus {
      */
     <T> void addListener(Class<T> type, Consumer<T> consumer);
 
+    /**
+     * Registers an event listener with the receiveCancelled flag (NeoForge
+     * convention overload). Under Aprism the flag is accepted and ignored;
+     * cancelled-event semantics are not modelled by the shim bus.
+     *
+     * @param receiveCancelled whether to receive cancelled events
+     * @param type             the event class
+     * @param consumer         the listener invoked when an event of {@code type} is posted
+     * @param <T>              the event type
+     */
+    default <T> void addListener(boolean receiveCancelled, Class<T> type, Consumer<T> consumer) {
+        addListener(type, consumer);
+    }
+
+    /**
+     * Registers an event listener with priority and cancelled-receipt flags
+     * (full NeoForge convention overload, used by mods that wrap registration
+     * in their own helpers). Priority ordering is not modelled by the shim
+     * bus; the flag arguments are accepted and ignored.
+     *
+     * @param priority         the listener priority
+     * @param receiveCancelled whether to receive cancelled events
+     * @param type             the event class
+     * @param consumer         the listener invoked when an event of {@code type} is posted
+     * @param <T>              the event type
+     */
+    default <T> void addListener(EventPriority priority, boolean receiveCancelled,
+            Class<T> type, Consumer<T> consumer) {
+        addListener(type, consumer);
+    }
+
     /**
      * Registers a generic event listener.
      *

src/main/java/net/neoforged/fml/ModContainer.java

@@ -0,0 +1,46 @@
+package net.neoforged.fml;
+
+import java.util.logging.Logger;
+
+import net.neoforged.fml.config.ModConfig;
+import net.neoforged.fml.config.ModConfig.Type;
+
+/**
+ * NeoForge API shim: per-mod container. The real container carries the mod
+ * metadata, config registration, and extension points; under Aprism only the
+ * surface mods touch during construction is provided. {@link #registerConfig}
+ * accepts and logs the request without persisting anything.
+ *
+ * @author BlockConnect@StarsailsClover
+ */
+public class ModContainer {
+
+    private static final Logger LOG = Logger.getLogger(ModContainer.class.getName());
+
+    private final String modId;
+
+    /**
+     * @param modId the mod id this container represents
+     */
+    public ModContainer(String modId) {
+        this.modId = modId;
+    }
+
+    /**
+     * @return the mod id
+     */
+    public String getModId() {
+        return modId;
+    }
+
+    /**
+     * Registers a config with the container (no-op under Aprism; logged).
+     *
+     * @param type config scope
+     * @param spec the config spec
+     */
+    public void registerConfig(Type type, net.neoforged.fml.config.IConfigSpec spec) {
+        LOG.info("[shim] registerConfig(" + type + ") for " + modId
+                + " accepted (no persistence under Aprism)");
+    }
+}

src/main/java/net/neoforged/fml/ModList.java

@@ -0,0 +1,74 @@
+package net.neoforged.fml;
+
+import java.nio.file.Path;
+import java.util.List;
+
+/**
+ * NeoForge API shim: the loaded-mod list facade. Mods query {@code ModList.get().isLoaded(id)}
+ * for inter-mod presence checks. Under Aprism answers come from the ids
+ * registered by the SupportExtension handler during mod discovery.
+ *
+ * @author BlockConnect@StarsailsClover
+ */
+public final class ModList {
+
+    private static volatile List<String> loadedIds = List.of();
+
+    private ModList() {
+    }
+
+    /**
+     * Returns the shared ModList instance.
+     *
+     * @return the singleton
+     */
+    public static ModList get() {
+        return Holder.INSTANCE;
+    }
+
+    /**
+     * Updates the known mod ids. Called by the Aprism handler after each
+     * discovery pass.
+     *
+     * @param ids all discovered mod ids
+     */
+    public static void setLoadedMods(List<String> ids) {
+        loadedIds = List.copyOf(ids);
+    }
+
+    /**
+     * Checks whether a mod is loaded.
+     *
+     * @param id the mod id
+     * @return true if loaded
+     */
+    public boolean isLoaded(String id) {
+        return loadedIds.contains(id);
+    }
+
+    /**
+     * Returns all loaded mod ids.
+     *
+     * @return unmodifiable list
+     */
+    public List<String> getLoadedMods() {
+        return loadedIds;
+    }
+
+    /**
+     * Returns annotation scan data across all mod files (empty under Aprism:
+     * the shim runtime performs no annotation scan pass).
+     *
+     * @return unmodifiable empty list
+     */
+    public List<net.neoforged.neoforgespi.language.ModFileScanData> getAllScanData() {
+        return List.of();
+    }
+
+    private static final class Holder {
+        private Holder() {
+        }
+
+        static final ModList INSTANCE = new ModList();
+    }
+}

src/main/java/net/neoforged/fml/ModLoadingContext.java

@@ -0,0 +1,54 @@
+package net.neoforged.fml;
+
+import net.neoforged.fml.config.ModConfig;
+
+/**
+ * NeoForge API shim: the mod loading context handed to mods for container
+ * operations. The real FML provides one context per active mod; this shim
+ * returns a shared instance whose {@link #getActiveContainer()} answers a
+ * per-call stub backed by the most recently constructed mod id.
+ *
+ * @author BlockConnect@StarsailsClover
+ */
+public final class ModLoadingContext {
+
+    private static volatile String activeModId = "unknown";
+
+    private ModLoadingContext() {
+    }
+
+    /**
+     * Returns the shared context instance (real FML semantics).
+     *
+     * @return the singleton context
+     */
+    public static ModLoadingContext get() {
+        return Holder.INSTANCE;
+    }
+
+    /**
+     * Sets the id reported by {@link #getActiveContainer()}.
+     * Called by the Aprism handler before constructing each mod.
+     *
+     * @param modId the currently-loading mod id
+     */
+    public static void setActiveModId(String modId) {
+        activeModId = modId;
+    }
+
+    /**
+     * Returns the active mod container stub.
+     *
+     * @return a minimal {@link ModContainer} for the active mod
+     */
+    public ModContainer getActiveContainer() {
+        return new ModContainer(activeModId);
+    }
+
+    private static final class Holder {
+        private Holder() {
+        }
+
+        static final ModLoadingContext INSTANCE = new ModLoadingContext();
+    }
+}

src/main/java/net/neoforged/fml/config/IConfigSpec.java

@@ -0,0 +1,18 @@
+package net.neoforged.fml.config;
+
+/**
+ * NeoForge API shim: marker interface for config specs. The real interface
+ * carries validation and reload contracts; under Aprism it exists only so
+ * {@code ModContainer.registerConfig(Type, IConfigSpec)} resolves.
+ *
+ * @author BlockConnect@StarsailsClover
+ */
+public interface IConfigSpec {
+
+    /**
+     * @return true if the spec is considered loaded (always true under Aprism)
+     */
+    default boolean isLoaded() {
+        return true;
+    }
+}

src/main/java/net/neoforged/fml/config/ModConfig.java

@@ -0,0 +1,19 @@
+package net.neoforged.fml.config;
+
+/**
+ * NeoForge API shim: config type holder. The real class carries file paths
+ * and reload callbacks; under Aprism only the {@link Type} enum and a
+ * constructor-compatible shape are provided.
+ *
+ * @author BlockConnect@StarsailsClover
+ */
+public abstract class ModConfig {
+
+    /** Config scope. */
+    public enum Type {
+        CLIENT,
+        COMMON,
+        SERVER,
+        STARTUP
+    }
+}

src/main/java/net/neoforged/fml/event/IModBusEvent.java

@@ -0,0 +1,11 @@
+package net.neoforged.fml.event;
+
+/**
+ * NeoForge API shim: marker interface for mod-bus events. The real FML uses
+ * it to validate that an event type belongs on the mod-scoped bus; under
+ * Aprism it exists so event-class resolution succeeds.
+ *
+ * @author BlockConnect@StarsailsClover
+ */
+public interface IModBusEvent {
+}