feat(events): record exact ability refunds

src/main/java/games/dmg/fantasystick/FantasyStickPlugin.java

@@ -168,6 +168,7 @@ public final class FantasyStickPlugin extends JavaPlugin {
     private games.dmg.fantasystick.events.RareEventBridge rareEvents;
     private games.dmg.fantasystick.events.BookEventBridge bookEvents;
     private games.dmg.fantasystick.events.ProgressionEventBridge progressionEvents;
+    private games.dmg.fantasystick.events.AbilityEventBridge abilityEvents;
     private java.util.concurrent.CompletionStage<Void> configurationDrain = java.util.concurrent.CompletableFuture.completedStage(null);
 
     @Override public void onEnable() {
@@ -707,13 +708,14 @@ public final class FantasyStickPlugin extends JavaPlugin {
                 rareEvents = new games.dmg.fantasystick.events.RareEventBridge(eventLog::emit, Clock.systemUTC());rareShop.attachEvents(rareEvents);
                 bookEvents = new games.dmg.fantasystick.events.BookEventBridge(eventLog::emit, Clock.systemUTC());books.attachEvents(bookEvents);
                 progressionEvents = new games.dmg.fantasystick.events.ProgressionEventBridge(eventLog::emit, Clock.systemUTC());books.attachProgressionEvents(progressionEvents);
+                abilityEvents = new games.dmg.fantasystick.events.AbilityEventBridge(eventLog::emit, Clock.systemUTC());books.attachAbilityEvents(abilityEvents);
                 sessions.attachDownedEvents(downedEvents);
                 downedController.attachEvents(downedEvents);
                 revive.attachDownedEvents(downedEvents);
                 admin.attachDownedEvents(downedEvents);
                 getServer().getPluginManager().registerEvents(eventCapture, this);
             } catch (java.io.IOException failure) {
-                eventLog = null; eventCapture = null; downedEvents = null; rareEvents = null; bookEvents = null; progressionEvents = null;
+                eventLog = null; eventCapture = null; downedEvents = null; rareEvents = null; bookEvents = null; progressionEvents = null; abilityEvents = null;
                 getLogger().log(Level.WARNING,"Fantasy Stick local events are unavailable; gameplay remains enabled",failure);
             }
             getServer().getPluginManager().registerEvents(crafting, this);
@@ -816,7 +818,7 @@ public final class FantasyStickPlugin extends JavaPlugin {
         combatFeedback = null;
         var closingEvents = sessionEvents; sessionEvents = null;
         var closingEventLog = eventLog; eventLog = null;
-        var closingEventCapture = eventCapture; eventCapture = null; downedEvents = null; rareEvents = null; bookEvents = null; progressionEvents = null;
+        var closingEventCapture = eventCapture; eventCapture = null; downedEvents = null; rareEvents = null; bookEvents = null; progressionEvents = null; abilityEvents = null;
         var closingBooks = books; books = null;
         var closingPartyEvents = partyEvents; partyEvents = null;
         var closingPartyCombat = partyCombat; partyCombat = null;

src/main/java/games/dmg/fantasystick/book/CharacterBookController.java

@@ -39,6 +39,7 @@ public final class CharacterBookController implements Consumer<ControlInput>, Au
     private final Map<UUID, games.dmg.fantasystick.events.BookEventBridge.Request> pendingBookEvents = new ConcurrentHashMap<>();
     private games.dmg.fantasystick.events.BookEventBridge bookEvents;
     private games.dmg.fantasystick.events.ProgressionEventBridge progressionEvents;
+    private games.dmg.fantasystick.events.AbilityEventBridge abilityEvents;
     private final Map<UUID, Object> adminPending = new ConcurrentHashMap<>();
     private final Map<UUID, AdminView> adminViews = new ConcurrentHashMap<>();
     private final Map<UUID, SavedView> savedViews = new ConcurrentHashMap<>();
@@ -65,7 +66,7 @@ public final class CharacterBookController implements Consumer<ControlInput>, Au
                              int previous, int next) { }
     private record SavedView(String nonce, UUID administrator, UUID character, int previous, int next) { }
     private record StatView(String nonce, ControlInput input, java.math.BigInteger revision, CharacterRecord before) { }
-    private record AbilityView(String nonce, ControlInput input, java.math.BigInteger revision, java.util.Set<String> ids) { }
+    private record AbilityView(String nonce, ControlInput input, java.math.BigInteger revision, java.util.Set<String> ids, CharacterRecord before) { }
     private record PassiveView(String nonce, ControlInput input, java.math.BigInteger revision, java.util.Set<String> ids) { }
     private record RareView(String nonce,ControlInput input,java.util.Map<String,java.math.BigInteger> quantities){}
     private record ReskillView(String nonce,ControlInput input,games.dmg.fantasystick.shop.RareReskillService.Preview preview){}
@@ -122,6 +123,7 @@ public final class CharacterBookController implements Consumer<ControlInput>, Au
 
     public void attachEvents(games.dmg.fantasystick.events.BookEventBridge events){if(closed||bookEvents!=null)throw new IllegalStateException("Book events already attached or controller closed");bookEvents=Objects.requireNonNull(events);}
     public void attachProgressionEvents(games.dmg.fantasystick.events.ProgressionEventBridge events){if(closed||progressionEvents!=null)throw new IllegalStateException("Progression events already attached or controller closed");progressionEvents=Objects.requireNonNull(events);}
+    public void attachAbilityEvents(games.dmg.fantasystick.events.AbilityEventBridge events){if(closed||abilityEvents!=null)throw new IllegalStateException("Ability events already attached or controller closed");abilityEvents=Objects.requireNonNull(events);}
 
     @Override public void accept(ControlInput input) { load(input, 0, true); }
 
@@ -337,7 +339,7 @@ public final class CharacterBookController implements Consumer<ControlInput>, Au
         if ((!definitions.isEmpty() || !passiveDefinitions.isEmpty()) && end == allOverview.size()) {
             var abilityView = interactive ? new AbilityView(UUID.randomUUID().toString(), input, record.revision(),
                 definitions.stream().map(games.dmg.fantasystick.ability.AbilityDefinition::id)
-                    .collect(java.util.stream.Collectors.toUnmodifiableSet())) : null;
+                    .collect(java.util.stream.Collectors.toUnmodifiableSet()), record) : null;
             if (interactive && !definitions.isEmpty()) abilityViews.put(input.session().player(), abilityView);
             var passiveView = interactive ? new PassiveView(UUID.randomUUID().toString(), input, record.revision(),
                 passiveDefinitions.stream().map(games.dmg.fantasystick.passive.PassiveDefinition::id)
@@ -855,18 +857,15 @@ public final class CharacterBookController implements Consumer<ControlInput>, Au
         if (closed || abilityEngine == null || !unlock && !unlearn
                 || !(event.getCommonConnection() instanceof io.papermc.paper.connection.PlayerGameConnection connection)
                 || event.getTag() == null) return;
-        var player = connection.getPlayer();
+        var player = connection.getPlayer();String raw=event.getTag().string();if(raw.length()>120)return;var match=ABILITY_PAYLOAD.matcher(raw);if(!match.matches())return;String ability=match.group(2);
         var view = abilityViews.get(player.getUniqueId());
-        if (view == null || view.input().player() != player) return;
-        String raw = event.getTag().string();
-        if (raw.length() > 120) return;
-        var match = ABILITY_PAYLOAD.matcher(raw);
-        if (!match.matches() || !view.nonce().equals(match.group(1)) || !view.ids().contains(match.group(2))
-                || !abilityViews.remove(player.getUniqueId(), view) || !view.input().stillCurrent()) return;
-        String ability = match.group(2);
+        if (view == null || view.input().player() != player || !view.nonce().equals(match.group(1)) || !view.ids().contains(ability)
+                || !abilityViews.remove(player.getUniqueId(), view) || !view.input().stillCurrent()) {if(unlearn)refuseAbilityUnlearn(player,ability,"stale_forged_or_repeated_action");return;}
+        var audit=unlearn&&abilityEvents!=null?abilityEvents.begin(view.input(),view.before(),ability):null;
         var operation = unlock ? abilityEngine.purchase(view.input(), ability, view.revision())
             : abilityEngine.unlearn(view.input(), ability, view.revision());
         operation.whenComplete((mutation, failure) -> {
+            if(audit!=null){if(failure!=null)abilityEvents.failed(audit,"save_or_native_cleanup_uncertain");else abilityEvents.resolved(audit,mutation);}
             if (closed || !view.input().stillCurrent()) return;
             if (failure != null) {
                 report(view.input(), failure);
@@ -878,6 +877,8 @@ public final class CharacterBookController implements Consumer<ControlInput>, Au
         });
     }
 
+    private void refuseAbilityUnlearn(org.bukkit.entity.Player player,String ability,String reason){if(abilityEvents==null||abilities.find(ability).isEmpty())return;var active=sessions.active(player.getUniqueId()).filter(sessions::current).orElse(null);if(active==null)return;var current=sessions.currentRecord(active).orElse(null);if(current!=null)abilityEvents.refused(player,active,current,ability,reason);}
+
     @org.bukkit.event.EventHandler
     public void passiveAction(io.papermc.paper.event.player.PlayerCustomClickEvent event) {
         boolean unlock = PASSIVE_UNLOCK.equals(event.getIdentifier());

src/main/java/games/dmg/fantasystick/events/AbilityEventBridge.java

@@ -0,0 +1,51 @@
+package games.dmg.fantasystick.events;
+
+import games.dmg.fantasystick.ability.AbilityEngine;
+import games.dmg.fantasystick.persistence.CharacterRecord;
+import games.dmg.fantasystick.session.ControlInput;
+import games.dmg.fantasystick.session.EquipmentSessions;
+import java.nio.charset.StandardCharsets;
+import java.time.Clock;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Objects;
+import java.util.UUID;
+import java.util.function.Consumer;
+import org.bukkit.Location;
+
+/** Feature-owned exact ability-refund outcomes; never an authorization or refund authority. */
+public final class AbilityEventBridge {
+    public record Action(UUID actionId,EventInput.Context context,String ability,CharacterRecord before){
+        public Action{Objects.requireNonNull(actionId);Objects.requireNonNull(context);Objects.requireNonNull(ability);Objects.requireNonNull(before);}
+    }
+    private final Consumer<EventInput> sink;private final Clock clock;
+    public AbilityEventBridge(Consumer<EventInput> sink,Clock clock){this.sink=Objects.requireNonNull(sink);this.clock=Objects.requireNonNull(clock);}
+
+    public Action begin(ControlInput input,CharacterRecord before,String ability){
+        var action=new Action(UUID.randomUUID(),context(input.player(),input.session(),before.name()),ability,before);
+        emit("action.observed",action,"observed",null,null,null);return action;
+    }
+    public void refused(org.bukkit.entity.Player player,EquipmentSessions.Active active,CharacterRecord before,String ability,String reason){
+        var action=new Action(UUID.randomUUID(),context(player,active,before.name()),ability,before);emit("action.observed",action,"observed",null,null,null);emit("action.resolved",action,"refused",reason,null,null);
+    }
+    public void failed(Action action,String reason){emit("action.resolved",action,"failed",reason,null,null);}
+    public void resolved(Action action,AbilityEngine.Mutation mutation){
+        if(mutation!=null&&mutation.status()==games.dmg.fantasystick.persistence.CharacterStorage.AbilityMutationStatus.APPLIED&&mutation.record()!=null){
+            emit("action.resolved",action,"accepted","acknowledged",mutation.record(),"acknowledged");
+            emit("ability.unlearned",action,"accepted","acknowledged",mutation.record(),"acknowledged");
+        }else emit("action.resolved",action,"refused",mutation==null?"unavailable":mutation.status().name().toLowerCase(java.util.Locale.ROOT),mutation==null?null:mutation.record(),null);
+    }
+
+    private void emit(String type,Action action,String outcome,String reason,CharacterRecord after,String nativePublication){
+        var before=action.before();var data=new LinkedHashMap<String,Object>();data.put("action_kind","ability_unlearn");data.put("ability_id",action.ability());data.put("expected_revision",before.revision().toString());data.put("before_revision",before.revision().toString());data.put("points_before",before.unspentPoints().toString());data.put("outcome",outcome);
+        var beforeCooldown=before.cooldowns().get(action.ability());if(beforeCooldown!=null)data.put("cooldown_before",beforeCooldown.toString());
+        if(after!=null){data.put("after_revision",after.revision().toString());data.put("points_after",after.unspentPoints().toString());var afterCooldown=after.cooldowns().get(action.ability());if(afterCooldown!=null)data.put("cooldown_after",afterCooldown.toString());var cleared=new ArrayList<Integer>();for(int slot=0;slot<before.loadout().size();slot++)if(action.ability().equals(before.loadout().get(slot))&&(slot>=after.loadout().size()||!action.ability().equals(after.loadout().get(slot))))cleared.add(slot);data.put("cleared_slot_indexes",cleared);data.put("slot_index_base",0);}
+        if(nativePublication!=null){data.put("native_publication",nativePublication);data.put("owned_cleanup","invalidation_acknowledged_close_attempted");}
+        if(reason!=null)data.put(type.equals("ability.unlearned")?"native_boundary":"reason",reason);
+        try{sink.accept(new EventInput(id(action.actionId(),type),action.actionId(),clock.instant(),type,action.context(),Map.copyOf(data)));}catch(RuntimeException ignored){}
+    }
+    private EventInput.Context context(org.bukkit.entity.Player player,EquipmentSessions.Active active,String characterName){return new EventInput.Context(player.getUniqueId(),player.getName(),active.character(),characterName,active.session(),location(player.getLocation()));}
+    private EventInput.Location location(Location location){return new EventInput.Location(location.getWorld().getUID(),location.getWorld().getName(),location.getX(),location.getY(),location.getZ(),clock.instant(),"exact");}
+    private static UUID id(UUID action,String type){return UUID.nameUUIDFromBytes(("fantasystick:ability-unlearn:"+action+":"+type).getBytes(StandardCharsets.UTF_8));}
+}

src/nativeTest/java/games/dmg/fantasystick/CharacterBookNativeTest.java

@@ -22,7 +22,7 @@ class CharacterBookNativeTest {
     @BeforeAll static void bootstrap() throws Exception { NativeRuntime.bootstrap(); }
 
     @Test void bookEventSinkFailureCannotChangeTheAlreadyAuthorizedNativeBookPath() {
-        var player=org.mockito.Mockito.mock(org.bukkit.entity.Player.class);var world=org.mockito.Mockito.mock(org.bukkit.World.class);var record=org.mockito.Mockito.mock(games.dmg.fantasystick.persistence.CharacterRecord.class);var playerId=UUID.randomUUID();var active=new games.dmg.fantasystick.session.EquipmentSessions.Active(playerId,UUID.randomUUID(),UUID.randomUUID());org.mockito.Mockito.when(player.getUniqueId()).thenReturn(playerId);org.mockito.Mockito.when(player.getName()).thenReturn("Player");org.mockito.Mockito.when(world.getUID()).thenReturn(UUID.randomUUID());org.mockito.Mockito.when(world.getName()).thenReturn("world");org.mockito.Mockito.when(player.getLocation()).thenReturn(new org.bukkit.Location(world,1,2,3));org.mockito.Mockito.when(record.name()).thenReturn("Hero");org.mockito.Mockito.when(record.revision()).thenReturn(java.math.BigInteger.ONE);org.mockito.Mockito.when(record.stats()).thenReturn(java.util.Map.of(games.dmg.fantasystick.progression.Stat.CON,java.math.BigInteger.ZERO));org.mockito.Mockito.when(record.unspentPoints()).thenReturn(java.math.BigInteger.ONE);org.mockito.Mockito.when(record.maximumHealth()).thenReturn(java.math.BigDecimal.TEN);org.mockito.Mockito.when(record.health()).thenReturn(java.math.BigDecimal.ONE);var input=new games.dmg.fantasystick.session.ControlInput(player,active,0,"",games.dmg.fantasystick.session.ControlInput.Kind.BOOK,games.dmg.fantasystick.session.ControlInput.Gesture.USE,null,0,0,()->true);var bridge=new games.dmg.fantasystick.events.BookEventBridge(event->{throw new IllegalStateException("disk");},java.time.Clock.systemUTC());var progression=new games.dmg.fantasystick.events.ProgressionEventBridge(event->{throw new IllegalStateException("disk");},java.time.Clock.systemUTC());assertDoesNotThrow(()->{var request=bridge.request(input,record,0);bridge.opened(request,record,3,1);bridge.refused(request,"retry");var action=progression.begin(input,record,games.dmg.fantasystick.progression.Stat.CON,java.math.BigDecimal.ONE,java.math.BigDecimal.TEN,java.math.BigDecimal.valueOf(1024));progression.increased(action,record,"acknowledged",java.math.BigDecimal.ONE);});
+        var player=org.mockito.Mockito.mock(org.bukkit.entity.Player.class);var world=org.mockito.Mockito.mock(org.bukkit.World.class);var record=org.mockito.Mockito.mock(games.dmg.fantasystick.persistence.CharacterRecord.class);var playerId=UUID.randomUUID();var active=new games.dmg.fantasystick.session.EquipmentSessions.Active(playerId,UUID.randomUUID(),UUID.randomUUID());org.mockito.Mockito.when(player.getUniqueId()).thenReturn(playerId);org.mockito.Mockito.when(player.getName()).thenReturn("Player");org.mockito.Mockito.when(world.getUID()).thenReturn(UUID.randomUUID());org.mockito.Mockito.when(world.getName()).thenReturn("world");org.mockito.Mockito.when(player.getLocation()).thenReturn(new org.bukkit.Location(world,1,2,3));org.mockito.Mockito.when(record.name()).thenReturn("Hero");org.mockito.Mockito.when(record.revision()).thenReturn(java.math.BigInteger.ONE);org.mockito.Mockito.when(record.stats()).thenReturn(java.util.Map.of(games.dmg.fantasystick.progression.Stat.CON,java.math.BigInteger.ZERO));org.mockito.Mockito.when(record.unspentPoints()).thenReturn(java.math.BigInteger.ONE);org.mockito.Mockito.when(record.maximumHealth()).thenReturn(java.math.BigDecimal.TEN);org.mockito.Mockito.when(record.health()).thenReturn(java.math.BigDecimal.ONE);org.mockito.Mockito.when(record.cooldowns()).thenReturn(java.util.Map.of());org.mockito.Mockito.when(record.loadout()).thenReturn(java.util.List.of("","","","","","",""));var input=new games.dmg.fantasystick.session.ControlInput(player,active,0,"",games.dmg.fantasystick.session.ControlInput.Kind.BOOK,games.dmg.fantasystick.session.ControlInput.Gesture.USE,null,0,0,()->true);var bridge=new games.dmg.fantasystick.events.BookEventBridge(event->{throw new IllegalStateException("disk");},java.time.Clock.systemUTC());var progression=new games.dmg.fantasystick.events.ProgressionEventBridge(event->{throw new IllegalStateException("disk");},java.time.Clock.systemUTC());var abilityEvents=new games.dmg.fantasystick.events.AbilityEventBridge(event->{throw new IllegalStateException("disk");},java.time.Clock.systemUTC());assertDoesNotThrow(()->{var request=bridge.request(input,record,0);bridge.opened(request,record,3,1);bridge.refused(request,"retry");var action=progression.begin(input,record,games.dmg.fantasystick.progression.Stat.CON,java.math.BigDecimal.ONE,java.math.BigDecimal.TEN,java.math.BigDecimal.valueOf(1024));progression.increased(action,record,"acknowledged",java.math.BigDecimal.ONE);var unlearn=abilityEvents.begin(input,record,"fireball");abilityEvents.failed(unlearn,"save_failed");});
     }
 
     @Test void registeredOpenReachesOneAcknowledgedFeatureEventAfterAuthoritativeReadAndNativeOpen() throws Exception {

src/nativeTest/java/games/dmg/fantasystick/FireballNativeTest.java

@@ -258,6 +258,12 @@ class FireballNativeTest {
             assertTrue(b.messages.stream().anyMatch(message -> message.contains("ready in")),
                 "Transfer/reload must retain the original Fireball deadline after refund and relearn");
         }
+        var events=new java.util.ArrayList<com.google.gson.JsonObject>();try(var files=java.nio.file.Files.walk(data.resolve("events"))){for(var file:files.filter(path->path.getFileName().toString().endsWith(".jsonl")).toList())for(var line:java.nio.file.Files.readAllLines(file))if(!line.isBlank())events.add(com.google.gson.JsonParser.parseString(line).getAsJsonObject());}var unlearned=events.stream().filter(event->event.get("type").getAsString().endsWith("ability.unlearned")).toList();assertEquals(1,unlearned.size());var value=unlearned.getFirst().getAsJsonObject("data");assertEquals("fireball",value.get("ability_id").getAsString());assertEquals("39",value.get("points_before").getAsString());assertEquals("40",value.get("points_after").getAsString());assertEquals(java.util.List.of(0),value.getAsJsonArray("cleared_slot_indexes").asList().stream().map(com.google.gson.JsonElement::getAsInt).toList());assertEquals("acknowledged",value.get("native_publication").getAsString());assertEquals("invalidation_acknowledged_close_attempted",value.get("owned_cleanup").getAsString());assertEquals(value.get("cooldown_before").getAsString(),value.get("cooldown_after").getAsString());assertTrue(value.getAsJsonObject("location").has("world_id"));var action=value.get("action_id").getAsString();assertEquals(1,events.stream().filter(event->event.get("type").getAsString().endsWith("action.observed")&&event.getAsJsonObject("data").has("action_kind")&&event.getAsJsonObject("data").get("action_kind").getAsString().equals("ability_unlearn")&&event.getAsJsonObject("data").get("action_id").getAsString().equals(action)).count());assertEquals(1,events.stream().filter(event->event.get("type").getAsString().endsWith("action.resolved")&&event.getAsJsonObject("data").has("action_kind")&&event.getAsJsonObject("data").get("action_kind").getAsString().equals("ability_unlearn")&&event.getAsJsonObject("data").get("action_id").getAsString().equals(action)&&event.getAsJsonObject("data").get("outcome").getAsString().equals("accepted")).count());assertTrue(events.stream().filter(event->event.get("type").getAsString().endsWith("action.resolved")&&event.getAsJsonObject("data").has("action_kind")&&event.getAsJsonObject("data").get("action_kind").getAsString().equals("ability_unlearn")).map(event->event.getAsJsonObject("data")).anyMatch(data->data.get("outcome").getAsString().equals("refused")&&data.get("reason").getAsString().equals("stale_forged_or_repeated_action")));
+    }
+
+    @Test void failedBookUnlearnResolvesWithoutInventingARefundEvent() throws Exception {
+        try(var f=new FantasyStickLifecycleNativeTest.Fixture(data)){f.plugin.setEnabled(true);var a=new FantasyStickLifecycleNativeTest.Actor(data);withFireball(data,a,12);f.players.put(a.core.id,a.player);f.activate(a);PartyBookNativeTest.open(f,a);var unlearn=PartyBookNativeTest.button(a,"[Unlearn]");try(var channel=java.nio.channels.FileChannel.open(data.resolve("characters/.records.lock"),java.nio.file.StandardOpenOption.WRITE);var lock=channel.lock()){assertTrue(lock.isValid());PartyBookNativeTest.click(f,a,unlearn);PartyBookNativeTest.drain(f);PartyBookNativeTest.drain(f);}var storage=(games.dmg.fantasystick.persistence.CharacterStorage)FantasyStickLifecycleNativeTest.Fixture.field(f.plugin,"characters");assertTrue(storage.find(a.core.record.id()).get().orElseThrow().learned().contains("fireball"));f.plugin.setEnabled(false);f.awaitWorkers();}
+        var events=new java.util.ArrayList<com.google.gson.JsonObject>();try(var files=java.nio.file.Files.walk(data.resolve("events"))){for(var file:files.filter(path->path.getFileName().toString().endsWith(".jsonl")).toList())for(var line:java.nio.file.Files.readAllLines(file))if(!line.isBlank())events.add(com.google.gson.JsonParser.parseString(line).getAsJsonObject());}assertEquals(0,events.stream().filter(event->event.get("type").getAsString().endsWith("ability.unlearned")).count());assertTrue(events.stream().filter(event->event.get("type").getAsString().endsWith("action.resolved")&&event.getAsJsonObject("data").has("action_kind")&&event.getAsJsonObject("data").get("action_kind").getAsString().equals("ability_unlearn")).map(event->event.getAsJsonObject("data")).anyMatch(value->value.get("outcome").getAsString().equals("failed")&&value.get("reason").getAsString().equals("save_or_native_cleanup_uncertain")));
     }
 
     @Test void partyAndMixedModeProjectileHitsPreserveProtectionCancellation() throws Exception {