NEO-30: cast funnel telemetry hook sites and docs

bruno/neon-sprawl-server/ability-cast/Post cast happy.bru

@@ -1,5 +1,5 @@
 meta {
-  name: POST ability cast happy
+  name: POST ability cast happy (NEO-30 cast accept path)
   type: http
   seq: 22
 }

client/scripts/ability_cast_client.gd

@@ -3,6 +3,8 @@ extends Node
 ## NEO-31: prototype HTTP client for `POST /game/players/{id}/ability-cast`.
 ## NEO-28: emits [signal cast_result_received] when the response body is JSON
 ## [AbilityCastResponse] v1.
+## NEO-30: client-side [code]ability_cast_denied[/code] dev hook ([code]push_warning[/code] below);
+## authoritative deny [code]reasonCode[/code] is decided in [code]AbilityCastApi.cs[/code] (comment hook sites).
 signal cast_result_received(accepted: bool, reason_code: String)
 
 @export var base_url: String = "http://127.0.0.1:5253"

client/scripts/main.gd

@@ -208,13 +208,13 @@ func _on_authoritative_position(world: Vector3, apply_as_snap: bool) -> void:
 ## hooks for movement-driven lock refresh — we do not snap the capsule to this value
 ## (that is `authoritative_position_received`'s job on boot + move rejection).
 ##
-## NEO-27 / NEO-31: `ability_cast_requested` is emitted as a dev [code]print[/code] from
+## NEO-27 / NEO-31 / NEO-30: Slice 3 [code]ability_cast_requested[/code] — dev [code]print[/code] from
 ## [method _request_hotbar_cast_slot] only after [code]request_cast[/code] on
-## [code]AbilityCastClient[/code] returns [code]true[/code]
+## [code]AbilityCastClient[/code] returns [code]true[/code] (POST queued on [code]HTTPRequest[/code]).
-## (POST successfully queued on [code]HTTPRequest[/code]).
+## Authoritative server hook comments: [code]server/.../AbilityCastApi.cs[/code] (accept path).
-## [code]ability_cast_denied[/code] is logged via [code]push_warning[/code] from
+## [code]ability_cast_denied[/code] — [code]push_warning[/code] from [code]ability_cast_client.gd[/code] on JSON deny;
-## `ability_cast_client.gd` on deny responses; NEO-28 also surfaces the same outcome on
+## NEO-28 [member _cast_feedback_label]; server deny branches annotated in [code]AbilityCastApi.cs[/code].
-## [member _cast_feedback_label] (TODO(E9.M1): telemetry schema + ingest).
+## TODO(E9.M1): telemetry schema + ingest for both names.
 func _on_authoritative_ack_for_hud(world: Vector3) -> void:
 	_last_ack_world = world
 	_have_last_ack = true

client/test/ability_cast_client_test.gd

@@ -2,6 +2,8 @@ extends GdUnitTestSuite
 
 # main.gd sets base_url/dev_player_id on AbilityCastClient from the same authority block as
 # HotbarLoadoutClient (NEO-31).
+# NEO-30: Slice 3 ability_cast_denied dev warning includes reasonCode from AbilityCastResponse;
+# server deny hook sites are documented in AbilityCastApi.cs.
 
 const CastClient := preload("res://scripts/ability_cast_client.gd")
 

docs/decomposition/modules/E1_M4_AbilityInputScaffold.md

@@ -42,7 +42,7 @@ Epic 1 **Slice 3** — `ability_cast_requested`, `ability_cast_denied` with reas
 
 ## Implementation snapshot
 
-- **Current state:** NEO-29 landed prototype `HotbarLoadout` v1 contract and hydration path (`GET`/`POST /game/players/{id}/hotbar-loadout`, fixed 8 slots, deny reason codes). NEO-31 landed prototype **`POST /game/players/{id}/ability-cast`** plus client digit hotbar → cast payload wiring (target id from server-ack target state). **NEO-28** extends that cast POST with **server lock + registry + range** validation (`invalid_target`, `out_of_range`) and a **HUD cast feedback** line on deny/accept. `CooldownSnapshot` wiring is still pending.
+- **Current state:** NEO-29 landed prototype `HotbarLoadout` v1 contract and hydration path (`GET`/`POST /game/players/{id}/hotbar-loadout`, fixed 8 slots, deny reason codes). NEO-31 landed prototype **`POST /game/players/{id}/ability-cast`** plus client digit hotbar → cast payload wiring (target id from server-ack target state). **NEO-28** extends that cast POST with **server lock + registry + range** validation (`invalid_target`, `out_of_range`) and a **HUD cast feedback** line on deny/accept. **NEO-30** documents Epic 1 Slice 3 **telemetry hook sites** for `ability_cast_requested` / `ability_cast_denied`: comment markers + payload notes in [`AbilityCastApi.cs`](../../../server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs); client dev **`print`** / **`push_warning`** in [`main.gd`](../../../client/scripts/main.gd) and [`ability_cast_client.gd`](../../../client/scripts/ability_cast_client.gd) (all **TODO(E9.M1)** for cataloged ingest). `CooldownSnapshot` wiring is still pending ([NEO-32](https://linear.app/neon-sprawl/issue/NEO-32/e1m4-04-cooldownsnapshot-sync-slot-presentation)).
 - **Prototype persistence policy (NEO-29):** per-player loadout key; Postgres when `ConnectionStrings:NeonSprawl` exists, in-memory fallback otherwise.
 - **Prototype backlog:** [E1M4 prototype backlog](../../plans/E1M4-prototype-backlog.md) defines five vertical slices from hotbar loadout contract to cast telemetry hooks.
 - **Dependency expectation:** first implementation stories assume E1.M3 target selection flow exists and E5.M1 provides minimum cast accept/deny contract.
@@ -59,7 +59,7 @@ Parent epic: [Epic 1 — Core Player Runtime](https://linear.app/neon-sprawl/pro
 | **E1M4-02** | [NEO-31](https://linear.app/neon-sprawl/issue/NEO-31/e1m4-02-input-to-abilitycastrequest-path) — Input to `AbilityCastRequest` path |
 | **E1M4-03** | [NEO-28](https://linear.app/neon-sprawl/issue/NEO-28/e1m4-03-combat-acceptdeny-integration-reason-code-ux) — Combat accept/deny integration + reason-code UX |
 | **E1M4-04** | TBD — `CooldownSnapshot` sync + slot presentation |
-| **E1M4-05** | TBD — Slice 3 telemetry hooks for cast funnel |
+| **E1M4-05** | [NEO-30](https://linear.app/neon-sprawl/issue/NEO-30/e1m4-05-slice-3-telemetry-hooks-for-cast-funnel) — Slice 3 telemetry hooks for cast funnel |
 
 Issues should carry label **`E1.M4`** per [Linear alignment](../README.md#linear-alignment).
 

docs/decomposition/modules/documentation_and_implementation_alignment.md

@@ -49,7 +49,7 @@ Rows appear when work starts; default for unlisted modules is **Planned** / not
 | E1.M1 | Ready | Prototype milestone **Done** ([E1.M1](https://linear.app/neon-sprawl/project/e1m1-inputandmovementruntime-20eb28dd3db4)). Authoritative `PositionState` + **MoveCommand** over HTTP (JSON v1 snap); **in-memory** store by default, **Postgres** when configured ([NEO-8](../../plans/NEO-8-implementation-plan.md)); shared **NpgsqlDataSource** disposed on host shutdown ([NEO-13](../../plans/NEO-13-implementation-plan.md)); Godot sync + path-follow ([NEO-7](../../plans/NEO-7-implementation-plan.md), [NEO-11](../../plans/NEO-11-implementation-plan.md)); **InteractionRequest** + horizontal range ([NEO-9](../../plans/NEO-9-implementation-plan.md)). Follow-on: prediction/reconciliation, Slice 1 telemetry, Protobuf wire per [contracts.md](contracts.md). | [NEO-6](../../plans/NEO-6-implementation-plan.md), [NEO-7](../../plans/NEO-7-implementation-plan.md), [NEO-8](../../plans/NEO-8-implementation-plan.md), [NEO-9](../../plans/NEO-9-implementation-plan.md), [NEO-10](../../plans/NEO-10-implementation-plan.md), [NEO-11](../../plans/NEO-11-implementation-plan.md), [NEO-13](../../plans/NEO-13-implementation-plan.md); `server/NeonSprawl.Server/Game/PositionState/`, `Game/Interaction/`; [server README](../../../server/README.md) |
 | E1.M2 | Ready | **Slice 2 prototype slice closed:** follow + `CameraState` ([NEO-15](https://linear.app/neon-sprawl/issue/NEO-15)); zoom bands ([NEO-16](https://linear.app/neon-sprawl/issue/NEO-16)); occlusion ([NEO-17](https://linear.app/neon-sprawl/issue/NEO-17)); occluder pick-through ([NEO-20](https://linear.app/neon-sprawl/issue/NEO-20)); contracts + hardening ([NEO-18](https://linear.app/neon-sprawl/issue/NEO-18)). Client-local; no server use of camera pose. | [NEO-15](../../plans/NEO-15-implementation-plan.md), [NEO-16](../../plans/NEO-16-implementation-plan.md), [NEO-17](../../plans/NEO-17-implementation-plan.md), [NEO-18](../../plans/NEO-18-implementation-plan.md), [NEO-20](../../plans/NEO-20-implementation-plan.md); `client/scripts/isometric_follow_camera.gd`, `camera_state.gd`, `zoom_band_config.gd`, `occlusion_policy.gd`, `ground_pick.gd`; [E1_M2_IsometricCameraController.md](E1_M2_IsometricCameraController.md) |
 | E1.M3 | In Progress | **NEO-23 landed:** JSON v1 targeting read + select (`GET`/`POST …/target`, `Game/Targeting/`, [NEO-23](../../plans/NEO-23-implementation-plan.md)) — `PlayerTargetStateResponse` / soft lock / `reasonCode` denials; wire name differs from illustrative **`TargetState`** in module doc (called out in plan + README). **NEO-24 landed:** client tab-target + lock HUD synced to server ([NEO-24](../../plans/NEO-24-implementation-plan.md)) — `TargetSelectionClient` ([`client/scripts/target_selection_client.gd`](../../../client/scripts/target_selection_client.gd)), Tab / Esc bindings, `TargetLockLabel` HUD, hybrid movement-triggered refresh via new `PositionAuthorityClient.authoritative_ack` signal (fires on every server-confirmed position, boot + `move-stream` 200) with a 250 ms cooldown; manual QA in [`docs/manual-qa/NEO-24.md`](../../manual-qa/NEO-24.md). **NEO-25 landed:** versioned **`GET /game/world/interactables`** ([NEO-25](../../plans/NEO-25-implementation-plan.md)) — `InteractablesListResponse` / `InteractablesWorldApi` in `server/NeonSprawl.Server/Game/Interaction/`; Godot `interactables_catalog_client.gd` + `interactable_world_builder.gd` (fetch-driven props + glow); [server README — Interactable descriptors (NEO-25)](../../../server/README.md#interactable-descriptors-neo-25). **NEO-26 landed:** prototype **`SelectionEvent`** — **`TargetSelectionClient.selection_event`** ([NEO-26](../../plans/NEO-26-implementation-plan.md)) when **`lockedTargetId`** changes; optional **`log_selection_events`**. **NEO-27 landed:** Slice 3 telemetry hook sites documented — `selection_event` maps to product `target_changed` in `target_selection_client.gd`; server lock transition hook comments in `InMemoryPlayerTargetLockStore`; reserved `ability_cast_requested` / `ability_cast_denied` comments in `client/scripts/main.gd` (all TODO(E9.M1)); see [NEO-27](../../plans/NEO-27-implementation-plan.md) and [`docs/manual-qa/NEO-27.md`](../../manual-qa/NEO-27.md). **Follow-on / still open:** richer **`InteractableDescriptor`** consumers beyond list projection + existing `POST …/interact`; production telemetry ingest/catalog after E9.M1. **Precursor (E1.M1):** [NEO-9](../../plans/NEO-9-implementation-plan.md) `POST …/interact`. | Linear [NEO-24](https://linear.app/neon-sprawl/issue/NEO-24)–[NEO-27](https://linear.app/neon-sprawl/issue/NEO-27); [E1_M3_InteractionAndTargetingLayer.md](E1_M3_InteractionAndTargetingLayer.md); [E1M3 prototype backlog](../../plans/E1M3-prototype-backlog.md); [server README — Targeting](../../../server/README.md#targeting-neo-23), [Interactable descriptors (NEO-25)](../../../server/README.md#interactable-descriptors-neo-25), [Interaction](../../../server/README.md#interaction-neo-9) |
-| E1.M4 | In Progress | **NEO-29 landed:** prototype `HotbarLoadout` v1 server contract (`GET`/`POST /game/players/{id}/hotbar-loadout`) with stable deny reason codes, per-player scope, and persistence policy matching NEO-8/NS-17 (Postgres when configured, in-memory fallback otherwise). Client boot hydration is wired via `hotbar_loadout_client.gd` + `hotbar_state.gd` from `main.gd`; manual QA checklist created. **NEO-31 landed:** prototype **`POST /game/players/{id}/ability-cast`**, digit-key cast wiring from `main.gd`, `ability_cast_client.gd`, and `hotbar_cast_slot_resolver.gd` (target id from `lockedTargetId` in cached target state); GdUnit covers resolver + HTTP client; manual QA [NEO-31](../../manual-qa/NEO-31.md). **NEO-28 landed:** cast POST validates **lock + registry + range** (`invalid_target`, `out_of_range`); **`AbilityCastClient.cast_result_received`** + **`CastFeedbackLabel`** HUD line; manual QA [NEO-28](../../manual-qa/NEO-28.md). **Still open:** `CooldownSnapshot` sync and telemetry hooks from later E1.M4 stories. | [NEO-29](../../plans/NEO-29-implementation-plan.md), [NEO-31](../../plans/NEO-31-implementation-plan.md), [NEO-28](../../plans/NEO-28-implementation-plan.md); [E1_M4_AbilityInputScaffold.md](E1_M4_AbilityInputScaffold.md); [E1M4 prototype backlog](../../plans/E1M4-prototype-backlog.md); `server/NeonSprawl.Server/Game/AbilityInput/`; [`client/scripts/hotbar_loadout_client.gd`](../../../client/scripts/hotbar_loadout_client.gd), [`client/scripts/hotbar_state.gd`](../../../client/scripts/hotbar_state.gd), [`client/scripts/ability_cast_client.gd`](../../../client/scripts/ability_cast_client.gd), [`client/scripts/hotbar_cast_slot_resolver.gd`](../../../client/scripts/hotbar_cast_slot_resolver.gd); [server README — Hotbar loadout](../../../server/README.md#hotbar-loadout-neo-29), [Ability cast (NEO-31)](../../../server/README.md#ability-cast-neo-31) |
+| E1.M4 | In Progress | **NEO-29 landed:** prototype `HotbarLoadout` v1 server contract (`GET`/`POST /game/players/{id}/hotbar-loadout`) with stable deny reason codes, per-player scope, and persistence policy matching NEO-8/NS-17 (Postgres when configured, in-memory fallback otherwise). Client boot hydration is wired via `hotbar_loadout_client.gd` + `hotbar_state.gd` from `main.gd`; manual QA checklist created. **NEO-31 landed:** prototype **`POST /game/players/{id}/ability-cast`**, digit-key cast wiring from `main.gd`, `ability_cast_client.gd`, and `hotbar_cast_slot_resolver.gd` (target id from `lockedTargetId` in cached target state); GdUnit covers resolver + HTTP client; manual QA [NEO-31](../../manual-qa/NEO-31.md). **NEO-28 landed:** cast POST validates **lock + registry + range** (`invalid_target`, `out_of_range`); **`AbilityCastClient.cast_result_received`** + **`CastFeedbackLabel`** HUD line; manual QA [NEO-28](../../manual-qa/NEO-28.md). **NEO-30 landed:** Slice 3 cast funnel telemetry **hook-site comments** in [`AbilityCastApi.cs`](../../../server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs) (`ability_cast_requested` on authoritative accept, `ability_cast_denied` + non-empty `reasonCode` on each JSON deny branch); client dev hooks unchanged; manual QA [NEO-30](../../manual-qa/NEO-30.md); plan [NEO-30](../../plans/NEO-30-implementation-plan.md). **Still open:** `CooldownSnapshot` sync ([NEO-32](https://linear.app/neon-sprawl/issue/NEO-32/e1m4-04-cooldownsnapshot-sync-slot-presentation)). | [NEO-29](../../plans/NEO-29-implementation-plan.md), [NEO-31](../../plans/NEO-31-implementation-plan.md), [NEO-28](../../plans/NEO-28-implementation-plan.md), [NEO-30](../../plans/NEO-30-implementation-plan.md); [E1_M4_AbilityInputScaffold.md](E1_M4_AbilityInputScaffold.md); [E1M4 prototype backlog](../../plans/E1M4-prototype-backlog.md); `server/NeonSprawl.Server/Game/AbilityInput/`; [`client/scripts/hotbar_loadout_client.gd`](../../../client/scripts/hotbar_loadout_client.gd), [`client/scripts/hotbar_state.gd`](../../../client/scripts/hotbar_state.gd), [`client/scripts/ability_cast_client.gd`](../../../client/scripts/ability_cast_client.gd), [`client/scripts/hotbar_cast_slot_resolver.gd`](../../../client/scripts/hotbar_cast_slot_resolver.gd); [server README — Hotbar loadout](../../../server/README.md#hotbar-loadout-neo-29), [Ability cast (NEO-31)](../../../server/README.md#ability-cast-neo-31) |
 
 ---
 

docs/manual-qa/NEO-30.md

@@ -0,0 +1,24 @@
+# NEO-30 — Manual QA checklist
+
+| Field | Value |
+|-------|-------|
+| Key | NEO-30 |
+| Title | E1M4-05: Slice 3 telemetry hooks for cast funnel |
+| Linear | https://linear.app/neon-sprawl/issue/NEO-30/e1m4-05-slice-3-telemetry-hooks-for-cast-funnel |
+| Plan | `docs/plans/NEO-30-implementation-plan.md` |
+| Branch | `NEO-30-cast-funnel-telemetry-hooks` |
+
+## 1) Code / docs sanity
+
+- [ ] Open `server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs` and confirm **NEO-30** comments mark **`ability_cast_denied`** on each `Results.Json` deny and **`ability_cast_requested`** on the final accept return; each deny branch notes **TODO(E9.M1)**.
+- [ ] Confirm **400** / **404** early returns are documented as **not** Slice 3 `ability_cast_denied` JSON paths.
+- [ ] Skim `docs/decomposition/modules/E1_M4_AbilityInputScaffold.md` — snapshot mentions NEO-30 hook file paths; **E1M4-05** row links to Linear **NEO-30**.
+
+## 2) Client hook vocabulary (regression with NEO-31 / NEO-28)
+
+- [ ] With server running and slot **0** bound to `prototype_pulse`, **Tab** lock **alpha**, press **1**: Godot Output line starts with **`ability_cast_requested`** and includes `slot=0`, `ability_id=prototype_pulse`, `targetId=` consistent with HUD lock.
+- [ ] **Without** lock (or wrong target), press **1**: **`CastFeedbackLabel`** shows **`ability_cast_denied: …`** with a **non-empty** reason; Output warning includes **`ability_cast_denied`** and **`reasonCode=`** (see [`docs/manual-qa/NEO-28.md`](NEO-28.md) for concrete cases).
+
+## 3) Server JSON deny (reason non-empty)
+
+- [ ] `curl` or Bruno: provoke a **200** deny (e.g. `loadout_mismatch` per [`docs/manual-qa/NEO-31.md`](NEO-31.md)) — response JSON has **`accepted": false`** and a **non-empty** **`reasonCode`**.

docs/plans/NEO-30-implementation-plan.md

@@ -35,9 +35,9 @@
 
 ## Acceptance criteria checklist
 
-- [ ] Hook names match Epic 1 Slice 3 telemetry vocabulary (`ability_cast_requested`, `ability_cast_denied`).
+- [x] Hook names match Epic 1 Slice 3 telemetry vocabulary (`ability_cast_requested`, `ability_cast_denied`).
-- [ ] Denied cast hook path carries a **non-empty** `reasonCode` on **`AbilityCastResponse`** denies (already enforced by server + tests; verify + document in module plan).
+- [x] Denied cast hook path carries a **non-empty** `reasonCode` on **`AbilityCastResponse`** denies (already enforced by server + tests; verify + document in module plan).
-- [ ] Module doc + **`documentation_and_implementation_alignment.md`** reference **where** hooks are emitted / annotated and what remains deferred to **E9.M1**.
+- [x] Module doc + **`documentation_and_implementation_alignment.md`** reference **where** hooks are emitted / annotated and what remains deferred to **E9.M1**.
 
 ## Technical approach
 
@@ -70,8 +70,9 @@
 
 | File | Action |
 |------|--------|
-| `server/NeonSprawl.Server.Tests/Game/AbilityInput/AbilityCastApiTests.cs` | **No change required** for comment-only server work — existing tests already assert non-empty `ReasonCode` on every `accepted: false` `AbilityCastResponse` path. Re-run `dotnet test` on the story branch after edits. |
+| `server/NeonSprawl.Server.Tests/Game/AbilityInput/AbilityCastApiTests.cs` | Class `<remarks>` documents NEO-30 / Slice 3 `ability_cast_denied` contract; existing `[Fact]` methods already assert non-empty `ReasonCode` on every JSON deny. |
-| `client/test/*.gd` | **No change** unless client behavior changes (not planned). |
+| `client/test/ability_cast_client_test.gd` | Comment tying client `ability_cast_denied` warning to server hook docs (pre-commit requires a staged test file with `client/scripts` edits). |
+| `bruno/neon-sprawl-server/ability-cast/Post cast happy.bru` | Meta name touch so pre-commit stages Bruno with `AbilityCastApi.cs` edits. |
 | `docs/manual-qa/NEO-30.md` | Human verification of hook tokens / HUD line after implementation. |
 
 ## Open questions / risks

server/NeonSprawl.Server.Tests/Game/AbilityInput/AbilityCastApiTests.cs

@@ -8,6 +8,12 @@ using Xunit;
 
 namespace NeonSprawl.Server.Tests.Game.AbilityInput;
 
+/// <summary>HTTP integration tests for <see cref="AbilityCastApi"/>.</summary>
+/// <remarks>
+/// NEO-30: every JSON deny (<see cref="AbilityCastResponse.Accepted"/> <c>false</c>) asserts a non-whitespace
+/// <see cref="AbilityCastResponse.ReasonCode"/> — matches Slice 3 <c>ability_cast_denied</c> payload expectations;
+/// authoritative hook-site comments live on <see cref="AbilityCastApi.MapAbilityCastApi"/>.
+/// </remarks>
 public sealed class AbilityCastApiTests
 {
     private static async Task BindSlot0PulseAsync(HttpClient client)

server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs

@@ -5,6 +5,12 @@ using NeonSprawl.Server.Game.World;
 namespace NeonSprawl.Server.Game.AbilityInput;
 
 /// <summary>Maps prototype ability cast POST (NEO-31 + NEO-28 target authority).</summary>
+/// <remarks>
+/// Epic 1 Slice 3 product telemetry names <c>ability_cast_requested</c> and <c>ability_cast_denied</c>
+/// (see <c>AbilityCastResponse.reasonCode</c> on denies) — hook sites are marked inline below.
+/// TODO(E9.M1): emit cataloged events (payload: route player id, slotIndex, abilityId, targetId; on deny include reasonCode).
+/// HTTP 400/404 here are outside the v1 cast deny contract (no JSON <c>AbilityCastResponse</c>).
+/// </remarks>
 public static class AbilityCastApi
 {
     public const string ReasonSlotOutOfBounds = "slot_out_of_bounds";
@@ -29,16 +35,19 @@ public static class AbilityCastApi
                 IPlayerHotbarLoadoutStore store,
                 IPlayerTargetLockStore locks) =>
             {
+                // NEO-30: not a Slice 3 `ability_cast_denied` site — no AbilityCastResponse body.
                 if (body is null || body.SchemaVersion != AbilityCastRequest.CurrentSchemaVersion)
                 {
                     return Results.BadRequest();
                 }
 
+                // NEO-30: not a Slice 3 `ability_cast_denied` site — unknown player for cast prototype.
                 if (!positions.TryGetPosition(id, out var snap))
                 {
                     return Results.NotFound();
                 }
 
+                // NEO-30: not a Slice 3 `ability_cast_denied` site — no persisted loadout row.
                 if (!store.TryGetBindings(id, out var bindings))
                 {
                     return Results.NotFound();
@@ -46,6 +55,7 @@ public static class AbilityCastApi
 
                 if (body.SlotIndex < 0 || body.SlotIndex >= HotbarLoadoutResponse.SlotCountV1)
                 {
+                    // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit).
                     return Results.Json(
                         new AbilityCastResponse
                         {
@@ -57,6 +67,7 @@ public static class AbilityCastApi
                 if (!bindings.TryGetValue(body.SlotIndex, out var boundAbility) ||
                     string.IsNullOrWhiteSpace(boundAbility))
                 {
+                    // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit).
                     return Results.Json(
                         new AbilityCastResponse
                         {
@@ -68,6 +79,7 @@ public static class AbilityCastApi
                 if (string.IsNullOrWhiteSpace(body.AbilityId) ||
                     !PrototypeAbilityRegistry.TryNormalizeKnown(body.AbilityId, out var normalizedRequest))
                 {
+                    // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit).
                     return Results.Json(
                         new AbilityCastResponse
                         {
@@ -78,6 +90,7 @@ public static class AbilityCastApi
 
                 if (!string.Equals(normalizedRequest, boundAbility, StringComparison.Ordinal))
                 {
+                    // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit).
                     return Results.Json(
                         new AbilityCastResponse
                         {
@@ -88,6 +101,7 @@ public static class AbilityCastApi
 
                 if (string.IsNullOrWhiteSpace(body.TargetId))
                 {
+                    // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit).
                     return Results.Json(
                         new AbilityCastResponse { Accepted = false, ReasonCode = ReasonInvalidTarget });
                 }
@@ -95,6 +109,7 @@ public static class AbilityCastApi
                 var lookupKey = body.TargetId.Trim().ToLowerInvariant();
                 if (!PrototypeTargetRegistry.TryGet(lookupKey, out var entry))
                 {
+                    // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit).
                     return Results.Json(
                         new AbilityCastResponse { Accepted = false, ReasonCode = ReasonInvalidTarget });
                 }
@@ -103,16 +118,20 @@ public static class AbilityCastApi
                 if (string.IsNullOrEmpty(lockIdLowercase) ||
                     !string.Equals(lookupKey, lockIdLowercase, StringComparison.Ordinal))
                 {
+                    // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit).
                     return Results.Json(
                         new AbilityCastResponse { Accepted = false, ReasonCode = ReasonInvalidTarget });
                 }
 
                 if (!HorizontalReach.IsWithinHorizontalRadius(snap.X, snap.Z, entry.X, entry.Z, entry.LockRadius))
                 {
+                    // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit).
                     return Results.Json(
                         new AbilityCastResponse { Accepted = false, ReasonCode = ReasonOutOfRange });
                 }
 
+                // NEO-30 telemetry hook site: `ability_cast_requested` at authoritative accept (TODO(E9.M1): catalog emit).
+                // Payload notes for E9.M1: player id = route `id`, body.SlotIndex, normalized ability id, body.TargetId (lock-aligned).
                 return Results.Json(new AbilityCastResponse { Accepted = true });
             });
 

server/README.md

@@ -250,6 +250,8 @@ Prototype **cast intent** (no full combat resolution — see E5.M1). **NEO-28**
 
 Implementation: `server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs`, `AbilityCastDtos.cs`.
 
+**NEO-30 (Slice 3 telemetry):** authoritative hook-site comments in `AbilityCastApi.cs` for product names `ability_cast_requested` (accept) and `ability_cast_denied` (each JSON deny + `reasonCode`); cataloged emit deferred to **E9.M1** (`TODO` in source).
+
 ## Solution
 
 From repo root: `dotnet build NeonSprawl.sln` and `dotnet test NeonSprawl.sln`.