From 340dbbe60d9f51f4b0d117d1877bab72ba0cc4bd Mon Sep 17 00:00:00 2001
From: VinPropane <don@donmail.org>
Date: Sun, 17 May 2026 19:10:12 -0400
Subject: [PATCH] NEO-49: add comment-only perk_unlock telemetry hook in
 TryUnlockPerks

---
 server/NeonSprawl.Server/Game/Mastery/PerkUnlockEngine.cs | 6 ++++++
 server/NeonSprawl.Server/Game/Mastery/PerkUnlockEvent.cs  | 2 +-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/server/NeonSprawl.Server/Game/Mastery/PerkUnlockEngine.cs b/server/NeonSprawl.Server/Game/Mastery/PerkUnlockEngine.cs
index 307308d..400369e 100644
--- a/server/NeonSprawl.Server/Game/Mastery/PerkUnlockEngine.cs
+++ b/server/NeonSprawl.Server/Game/Mastery/PerkUnlockEngine.cs
@@ -240,6 +240,12 @@ public sealed class PerkUnlockEngine(
         events = newIds
             .Select(pid => new PerkUnlockEvent(playerId, pid, skillId, tierIndex, branchId, source))
             .ToList();
+
+        // --- Telemetry hook site (NEO-49): future E9.M1 catalog event `perk_unlock` ---
+        // TODO(E9.M1): catalog emit — once per entry in `events` (idempotent reevaluation produces none).
+        // Planned payload fields: playerId, perkId, skillId, tierIndex, branchId, source (BranchPick | LevelUp).
+        // No ingest or ILogger here (comments-only).
+
         return true;
     }
 }
diff --git a/server/NeonSprawl.Server/Game/Mastery/PerkUnlockEvent.cs b/server/NeonSprawl.Server/Game/Mastery/PerkUnlockEvent.cs
index 63bde65..3d28bda 100644
--- a/server/NeonSprawl.Server/Game/Mastery/PerkUnlockEvent.cs
+++ b/server/NeonSprawl.Server/Game/Mastery/PerkUnlockEvent.cs
@@ -1,6 +1,6 @@
 namespace NeonSprawl.Server.Game.Mastery;
 
-/// <summary>Internal event when a perk becomes unlocked (NEO-47; NEO-49 telemetry).</summary>
+/// <summary>Internal event when a perk becomes unlocked (NEO-47). E9.M1 <c>perk_unlock</c> hook site: <see cref="PerkUnlockEngine"/> <c>TryUnlockPerks</c> (NEO-49).</summary>
 public enum PerkUnlockSource
 {
     BranchPick,