Internal: gate arena invariants by legendary instance ids

Author: LegendaryForge

docs/internal/arena-invariants.md

@@ -30,7 +30,7 @@ They must not introduce new public Core APIs and must not leak behavior into non
 
 ## Legendary-only gating (LOCKED)
 - Arena invariants apply only to Legendary encounters.
-- Legendary detection is captured at encounter creation time by tracking definition IDs when:
+- Legendary detection is captured at encounter creation time by tracking instance IDs when:
   - definition instanceof LegendaryEncounterDefinition
 - Gating is enforced internally in DefaultCoreRuntime wiring.
 

src/main/java/io/github/legendaryforge/legendary/core/internal/legendary/arena/ArenaInvariantBridge.java

@@ -11,6 +11,8 @@
 import java.util.Objects;
 import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.function.Consumer;
+import java.util.function.Predicate;
 
 /**
  * Internal bridge that forwards encounter lifecycle signals to arena invariants.
@@ -20,17 +22,32 @@
  */
 public final class ArenaInvariantBridge {
 
+    private static boolean always(UUID id) { return true; }
+
+    private static void noop(UUID id) {}
+
     private final ArenaInvariantRegistry registry;
+    private final Predicate<UUID> applyFilter;
+    private final Consumer<UUID> onCleanupPost;
 
     // Cleanup event only carries instanceId; this mapping routes cleanup to invariants.
     private final ConcurrentHashMap<UUID, ResourceId> instanceToDefinition = new ConcurrentHashMap<>();
 
     public ArenaInvariantBridge(ArenaInvariantRegistry registry) {
+        this(registry, ArenaInvariantBridge::always, ArenaInvariantBridge::noop);
+    }
+
+    public ArenaInvariantBridge(ArenaInvariantRegistry registry, Predicate<UUID> applyFilter, Consumer<UUID> onCleanupPost) {
         this.registry = Objects.requireNonNull(registry, "registry");
+        this.applyFilter = Objects.requireNonNull(applyFilter, "applyFilter");
+        this.onCleanupPost = Objects.requireNonNull(onCleanupPost, "onCleanupPost");
     }
 
     public void onStarted(EncounterStartedEvent event) {
         Objects.requireNonNull(event, "event");
+        if (!applyFilter.test(event.instanceId())) {
+            return;
+        }
         instanceToDefinition.put(event.instanceId(), event.definitionId());
         for (ArenaInvariant inv : registry.invariantsFor(event.definitionId())) {
             inv.onStart(event.instanceId());
@@ -39,27 +56,39 @@ public void onStarted(EncounterStartedEvent event) {
 
     public void onEnded(EncounterEndedEvent event) {
         Objects.requireNonNull(event, "event");
+        if (!applyFilter.test(event.instanceId())) {
+            return;
+        }
         for (ArenaInvariant inv : registry.invariantsFor(event.definitionId())) {
             inv.onEnd(event.instanceId());
         }
     }
 
     public void onCleanup(EncounterCleanupEvent event) {
         Objects.requireNonNull(event, "event");
-        ResourceId defId = instanceToDefinition.remove(event.instanceId());
+        UUID instanceId = event.instanceId();
+        ResourceId defId = instanceToDefinition.remove(instanceId);
         if (defId == null) {
+            onCleanupPost.accept(instanceId);
             return;
         }
-        for (ArenaInvariant inv : registry.invariantsFor(defId)) {
-            inv.onCleanup(event.instanceId());
+        if (applyFilter.test(instanceId)) {
+            for (ArenaInvariant inv : registry.invariantsFor(defId)) {
+                inv.onCleanup(instanceId);
+            }
         }
+        onCleanupPost.accept(instanceId);
     }
 
     public static List<Subscription> bind(EventBus bus, ArenaInvariantRegistry registry) {
+        return bind(bus, registry, ArenaInvariantBridge::always, ArenaInvariantBridge::noop);
+    }
+
+    public static List<Subscription> bind(EventBus bus, ArenaInvariantRegistry registry, Predicate<UUID> applyFilter, Consumer<UUID> onCleanupPost) {
         Objects.requireNonNull(bus, "bus");
         Objects.requireNonNull(registry, "registry");
 
-        ArenaInvariantBridge bridge = new ArenaInvariantBridge(registry);
+        ArenaInvariantBridge bridge = new ArenaInvariantBridge(registry, applyFilter, onCleanupPost);
         List<Subscription> subs = new ArrayList<>(3);
 
         subs.add(bus.subscribe(EncounterStartedEvent.class, bridge::onStarted));

…yDefinitionTrackingEncounterManager.java …aryInstanceTrackingEncounterManager.javasrc/main/java/io/github/legendaryforge/legendary/core/internal/legendary/arena/LegendaryDefinitionTrackingEncounterManager.java renamed to src/main/java/io/github/legendaryforge/legendary/core/internal/legendary/arena/LegendaryInstanceTrackingEncounterManager.java src/main/java/io/github/legendaryforge/legendary/core/internal/legendary/arena/LegendaryDefinitionTrackingEncounterManager.java renamed to src/main/java/io/github/legendaryforge/legendary/core/internal/legendary/arena/LegendaryInstanceTrackingEncounterManager.java

@@ -8,41 +8,41 @@
 import io.github.legendaryforge.legendary.core.api.encounter.EndReason;
 import io.github.legendaryforge.legendary.core.api.encounter.JoinResult;
 import io.github.legendaryforge.legendary.core.api.encounter.ParticipationRole;
-import io.github.legendaryforge.legendary.core.api.id.ResourceId;
 import io.github.legendaryforge.legendary.core.api.legendary.definition.LegendaryEncounterDefinition;
 import java.util.Objects;
 import java.util.Optional;
 import java.util.Set;
 import java.util.UUID;
 
 /**
- * Internal decorator that tracks which encounter definition ids are legendary based on runtime create() calls.
+ * Internal decorator that tracks which encounter instance ids are legendary based on runtime create() calls.
  *
- * <p>This provides a deterministic, low-overhead gating mechanism for internal arena invariants without introducing
+ * <p>This provides a deterministic, bounded gating mechanism for internal arena invariants without introducing
  * new public Core APIs or registries.
  */
-public final class LegendaryDefinitionTrackingEncounterManager implements EncounterManager {
+public final class LegendaryInstanceTrackingEncounterManager implements EncounterManager {
 
     private final EncounterManager delegate;
-    private final Set<ResourceId> legendaryDefinitionIds;
+    private final Set<UUID> legendaryInstanceIds;
 
-    public LegendaryDefinitionTrackingEncounterManager(EncounterManager delegate, Set<ResourceId> legendaryDefinitionIds) {
+    public LegendaryInstanceTrackingEncounterManager(EncounterManager delegate, Set<UUID> legendaryInstanceIds) {
         this.delegate = Objects.requireNonNull(delegate, "delegate");
-        this.legendaryDefinitionIds = Objects.requireNonNull(legendaryDefinitionIds, "legendaryDefinitionIds");
+        this.legendaryInstanceIds = Objects.requireNonNull(legendaryInstanceIds, "legendaryInstanceIds");
     }
 
-    public boolean isLegendary(ResourceId definitionId) {
-        Objects.requireNonNull(definitionId, "definitionId");
-        return legendaryDefinitionIds.contains(definitionId);
+    public boolean isLegendary(UUID instanceId) {
+        Objects.requireNonNull(instanceId, "instanceId");
+        return legendaryInstanceIds.contains(instanceId);
     }
 
     @Override
     public EncounterInstance create(EncounterDefinition definition, EncounterContext context) {
         Objects.requireNonNull(definition, "definition");
+        EncounterInstance instance = delegate.create(definition, context);
         if (definition instanceof LegendaryEncounterDefinition) {
-            legendaryDefinitionIds.add(definition.id());
+            legendaryInstanceIds.add(instance.instanceId());
         }
-        return delegate.create(definition, context);
+        return instance;
     }
 
     @Override

src/main/java/io/github/legendaryforge/legendary/core/internal/runtime/DefaultCoreRuntime.java

@@ -25,7 +25,7 @@
 import java.time.Clock;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.Set;
-import io.github.legendaryforge.legendary.core.internal.legendary.arena.LegendaryDefinitionTrackingEncounterManager;
+import io.github.legendaryforge.legendary.core.internal.legendary.arena.LegendaryInstanceTrackingEncounterManager;
 import io.github.legendaryforge.legendary.core.api.id.ResourceId;
 import java.util.Objects;
 import java.util.Optional;
@@ -85,21 +85,21 @@ public DefaultCoreRuntime(Optional<PlayerDirectory> players, Optional<PartyDirec
                 io.github.legendaryforge.legendary.core.api.encounter.event.EncounterEndedEvent.class,
                 durationTelemetry::onEnded);
 
-Set<ResourceId> legendaryDefinitionIds = ConcurrentHashMap.newKeySet();
+Set<java.util.UUID> legendaryInstanceIds = ConcurrentHashMap.newKeySet();
 PhaseGateInvariant phaseGate = new PhaseGateInvariant();
 
 ArenaInvariantRegistry arenaRegistry = definitionId -> {
     Objects.requireNonNull(definitionId, "definitionId");
-    return legendaryDefinitionIds.contains(definitionId) ? java.util.List.of(phaseGate) : java.util.List.of();
+    return java.util.List.of(phaseGate);
 };
 
-ArenaInvariantBridge.bind(bus, arenaRegistry);
+ArenaInvariantBridge.bind(bus, arenaRegistry, legendaryInstanceIds::contains, legendaryInstanceIds::remove);
 
         EncounterManager base = new DefaultEncounterManager(players, parties, Optional.of(bus));
         EncounterManager startGated = new LegendaryStartGatingEncounterManager(
                 base, new DefaultLegendaryStartPolicy(), new NoopLegendaryPenaltyStatus());
         EncounterManager enforced = new LegendaryAccessEnforcingEncounterManager(startGated, new DefaultLegendaryAccessPolicy());
-this.encounters = new LegendaryDefinitionTrackingEncounterManager(enforced, legendaryDefinitionIds);
+this.encounters = new LegendaryInstanceTrackingEncounterManager(enforced, legendaryInstanceIds);
 
         this.players = Objects.requireNonNull(players, "players");
         this.parties = Objects.requireNonNull(parties, "parties");

…initionTrackingEncounterManagerTest.java …nstanceTrackingEncounterManagerTest.javasrc/test/java/io/github/legendaryforge/legendary/core/internal/legendary/arena/LegendaryDefinitionTrackingEncounterManagerTest.java renamed to src/test/java/io/github/legendaryforge/legendary/core/internal/legendary/arena/LegendaryInstanceTrackingEncounterManagerTest.java src/test/java/io/github/legendaryforge/legendary/core/internal/legendary/arena/LegendaryDefinitionTrackingEncounterManagerTest.java renamed to src/test/java/io/github/legendaryforge/legendary/core/internal/legendary/arena/LegendaryInstanceTrackingEncounterManagerTest.java

@@ -1,5 +1,6 @@
 package io.github.legendaryforge.legendary.core.internal.legendary.arena;
 
+import io.github.legendaryforge.legendary.core.api.encounter.EncounterAccessPolicy;
 import io.github.legendaryforge.legendary.core.api.encounter.EncounterContext;
 import io.github.legendaryforge.legendary.core.api.encounter.EncounterDefinition;
 import io.github.legendaryforge.legendary.core.api.encounter.EncounterInstance;
@@ -9,7 +10,6 @@
 import io.github.legendaryforge.legendary.core.api.encounter.JoinResult;
 import io.github.legendaryforge.legendary.core.api.encounter.ParticipationRole;
 import io.github.legendaryforge.legendary.core.api.encounter.SpectatorPolicy;
-import io.github.legendaryforge.legendary.core.api.encounter.EncounterAccessPolicy;
 import io.github.legendaryforge.legendary.core.api.id.ResourceId;
 import io.github.legendaryforge.legendary.core.api.legendary.definition.LegendaryEncounterDefinition;
 import java.lang.reflect.Proxy;
@@ -21,16 +21,28 @@
 
 import static org.junit.jupiter.api.Assertions.*;
 
-final class LegendaryDefinitionTrackingEncounterManagerTest {
+final class LegendaryInstanceTrackingEncounterManagerTest {
 
     @Test
-    void tracksLegendaryDefinitionIdsOnCreate() {
-        Set<ResourceId> ids = ConcurrentHashMap.newKeySet();
+    void tracksLegendaryInstanceIdsOnCreate() {
+        Set<UUID> ids = ConcurrentHashMap.newKeySet();
+
+        UUID normalInstanceId = UUID.fromString("00000000-0000-0000-0000-000000000001");
+        UUID legendaryInstanceId = UUID.fromString("00000000-0000-0000-0000-000000000002");
+
+        ResourceId normalId = ResourceId.parse("test:normal_encounter");
+        ResourceId legendaryId = ResourceId.parse("test:legendary_encounter");
+
+        EncounterDefinition normalDef = proxyEncounterDefinition(EncounterDefinition.class, normalId);
+        LegendaryEncounterDefinition legendaryDef = proxyEncounterDefinition(LegendaryEncounterDefinition.class, legendaryId);
 
         EncounterManager delegate = new EncounterManager() {
             @Override
             public EncounterInstance create(EncounterDefinition definition, EncounterContext context) {
-                return proxyEncounterInstance();
+                if (definition instanceof LegendaryEncounterDefinition) {
+                    return proxyEncounterInstance(legendaryInstanceId);
+                }
+                return proxyEncounterInstance(normalInstanceId);
             }
 
             @Override
@@ -55,29 +67,25 @@ public Optional<EncounterInstance> byKey(EncounterKey key) {
             }
         };
 
-        LegendaryDefinitionTrackingEncounterManager mgr =
-                new LegendaryDefinitionTrackingEncounterManager(delegate, ids);
-
-        ResourceId normalId = ResourceId.parse("test:normal_encounter");
-        ResourceId legendaryId = ResourceId.parse("test:legendary_encounter");
-
-        EncounterDefinition normalDef = proxyEncounterDefinition(EncounterDefinition.class, normalId);
-        LegendaryEncounterDefinition legendaryDef = proxyEncounterDefinition(LegendaryEncounterDefinition.class, legendaryId);
+        LegendaryInstanceTrackingEncounterManager mgr =
+                new LegendaryInstanceTrackingEncounterManager(delegate, ids);
 
-        mgr.create(normalDef, null);
-        assertFalse(mgr.isLegendary(normalId));
+        EncounterInstance normalInstance = mgr.create(normalDef, null);
+        assertFalse(mgr.isLegendary(normalInstance.instanceId()));
 
-        mgr.create(legendaryDef, null);
-        assertTrue(mgr.isLegendary(legendaryId));
+        EncounterInstance legendaryInstance = mgr.create(legendaryDef, null);
+        assertTrue(mgr.isLegendary(legendaryInstance.instanceId()));
     }
 
-    private static EncounterInstance proxyEncounterInstance() {
+    private static EncounterInstance proxyEncounterInstance(UUID instanceId) {
         return (EncounterInstance) Proxy.newProxyInstance(
                 EncounterInstance.class.getClassLoader(),
                 new Class<?>[] { EncounterInstance.class },
                 (proxy, method, args) -> {
+                    if ("instanceId".equals(method.getName()) && method.getReturnType().equals(UUID.class)) {
+                        return instanceId;
+                    }
                     Class<?> rt = method.getReturnType();
-                    if (rt.equals(UUID.class)) return UUID.randomUUID();
                     if (rt.equals(Optional.class)) return Optional.empty();
                     if (rt.equals(int.class)) return 0;
                     if (rt.equals(boolean.class)) return false;
@@ -89,16 +97,14 @@ private static <T> T proxyEncounterDefinition(Class<T> type, ResourceId id) {
         return type.cast(Proxy.newProxyInstance(
                 type.getClassLoader(),
                 new Class<?>[] { type },
-                (proxy, method, args) -> {
-                    return switch (method.getName()) {
-                        case "id" -> id;
-                        case "displayName" -> "test";
-                        case "accessPolicy" -> EncounterAccessPolicy.PUBLIC;
-                        case "spectatorPolicy" -> SpectatorPolicy.ALLOW_VIEW_ONLY;
-                        case "maxParticipants" -> 0;
-                        case "maxSpectators" -> 0;
-                        default -> null;
-                    };
+                (proxy, method, args) -> switch (method.getName()) {
+                    case "id" -> id;
+                    case "displayName" -> "test";
+                    case "accessPolicy" -> EncounterAccessPolicy.PUBLIC;
+                    case "spectatorPolicy" -> SpectatorPolicy.ALLOW_VIEW_ONLY;
+                    case "maxParticipants" -> 0;
+                    case "maxSpectators" -> 0;
+                    default -> null;
                 }));
     }
 }

src/test/java/io/github/legendaryforge/legendary/core/internal/runtime/DefaultCoreRuntimeWiringTest.java

@@ -6,7 +6,7 @@
 import io.github.legendaryforge.legendary.core.api.encounter.EncounterManager;
 import io.github.legendaryforge.legendary.core.api.platform.CoreRuntime;
 import io.github.legendaryforge.legendary.core.internal.encounter.DefaultEncounterManager;
-import io.github.legendaryforge.legendary.core.internal.legendary.arena.LegendaryDefinitionTrackingEncounterManager;
+import io.github.legendaryforge.legendary.core.internal.legendary.arena.LegendaryInstanceTrackingEncounterManager;
 import io.github.legendaryforge.legendary.core.internal.legendary.manager.LegendaryAccessEnforcingEncounterManager;
 import io.github.legendaryforge.legendary.core.internal.legendary.start.LegendaryStartGatingEncounterManager;
 import java.lang.reflect.Field;
@@ -30,7 +30,7 @@ void defaultConstructorWiresLegendaryEncounterManagersInCorrectOrder() {
         CoreRuntime runtime = new DefaultCoreRuntime();
 
         EncounterManager encounters = runtime.encounters();
-          assertTrue(encounters instanceof LegendaryDefinitionTrackingEncounterManager, "top-level should track legendary definitions");
+          assertTrue(encounters instanceof LegendaryInstanceTrackingEncounterManager, "top-level should track legendary instances");
 
           EncounterManager enforcing = readDelegate(encounters);
           assertTrue(enforcing instanceof LegendaryAccessEnforcingEncounterManager, "second-level should enforce access");