don
/
neon-sprawl
mirror of https://github.com/ViPro-Technologies/neon-sprawl
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
neon-sprawl/docs/plans/NEO-27-implementation-plan.md

7.4 KiB
Raw Blame History

NEO-27 — Implementation plan

Story reference

Field Value
Key NEO-27
Title E1.M3: Slice 3 telemetry hook sites (target_changed, …)
Linear NEO-27
Slug E1M3-05
Git branch NEO-27-e1m3-slice-3-telemetry-hook-sites
Parent context Epic 1 — Core Player Runtime · E1M3 prototype backlog
Decomposition Epic 1 Slice 3 — telemetry hooks; E1.M3 — InteractionAndTargetingLayer

Kickoff clarifications

  • Q1 (resolved): Where should reserved ability_cast_requested / ability_cast_denied hook comments live for this story?
  • Answer: Keep them in client/scripts/main.gd (no extra placeholder script in NEO-27).
  • Why no additional blocking questions: Event names, scope, and out-of-scope were explicit in Linear + backlog docs; this was the only implementation-location decision not already settled.

Goal, scope, and out-of-scope

Goal: Establish documented hook sites for Epic 1 Slice 3 product telemetry names: target_changed (wired to real selection transitions), plus reserved (no-op / comment-only) sites for ability_cast_requested and ability_cast_denied until E1.M4 + E5.M1. All real ingest waits on TODO(E9.M1) per E9.M1 — TelemetryEventSchema.

In scope

  • Event names in code or doc comments matching epic Slice 3 (target_changed, ability_cast_requested, ability_cast_denied).
  • TODO(E9.M1) at each hook site until a catalog exists.
  • Optional dev logging when a flag is enabled (reuse or extend the NEO-26 log_selection_events pattern on the client; optional ILogger / Debug.WriteLine guard on server only if we add a clearly dev-gated path—prefer comments + single optional trace line consistent with repo norms).
  • documentation_and_implementation_alignment.md: extend the E1.M3 snapshot row to mention NEO-27 hook sites (per Linear acceptance; NEO-23 is already on main).

Out of scope

  • Production ingest, dashboards, OpenTelemetry.
  • Changing TargetState / HTTP contracts (NEO-23).
  • Implementing real ability cast requests (E1.M4).

Acceptance criteria checklist

  • Documented event names in-repo matching Slice 3: target_changed, ability_cast_requested, ability_cast_denied (latter two may be comment-only reserves).
  • TODO(E9.M1) at each hook site referencing schema work.
  • Optional dev logging for target_changed when a documented flag is on (or explicitly documented that an existing flag covers it, with log line including the product event name).
  • documentation_and_implementation_alignment.md E1.M3 row updated for NEO-27.

Technical approach

  1. target_changed (client) — Canonical prototype mirror: when TargetSelectionClient emits selection_event (NEO-26), the product telemetry name is target_changed (same transition: normalized lockedTargetId change, with cause / sequence carrying intent). Add a short class-level or method-level note on _maybe_emit_selection_event linking selection_event → target_changed. Optionally prefix dev print (when log_selection_events is true) with a literal target_changed token so grep and QA are unambiguous.

  2. target_changed (server) — Authoritative lock id transitions occur in InMemoryPlayerTargetLockStore.ApplySet / ApplyClear when the stored lock id actually changes (sequence bumps). Add // / /// comments (and TODO(E9.M1)) at those mutation success paths as the server-side hook site for target_changed. Rationale: single choke point; HTTP handlers stay thin.

  3. ability_cast_requested / ability_cast_denied (reserve) — No hotbar or cast route exists yet. Add a compact comment block in client/scripts/main.gd (or the first file E1.M4 will extend for input, if we prefer—Decision: main.gd next to other prototype wiring) listing the two event names and pointing to E1.M4 / E5.M1 + E9.M1. Optionally mirror a one-line reserve in TargetingApi.cs near denial responses noting that ability_cast_denied (with reasonCode) will attach to a future cast POST, not the current target-select deny path—avoids confusion with selection denials.

  4. Docs alignment — Append to the E1.M3 Snapshot cell: NEO-27 documents Slice 3 telemetry hook sites; link this plan.

Files to add

Path Rationale
docs/manual-qa/NEO-27.md Ticket-level manual verification checklist for Slice 3 telemetry hook-site behavior and expectations.

Files to modify

Path Rationale
client/scripts/target_selection_client.gd Document target_changed ↔ selection_event; optional dev log prefix; TODO(E9.M1).
server/NeonSprawl.Server/Game/Targeting/InMemoryPlayerTargetLockStore.cs Server authoritative target_changed hook site on lock id transitions.
client/scripts/main.gd Reserved comment block for ability_cast_requested / ability_cast_denied (E1.M4 + E5.M1).
server/NeonSprawl.Server/Game/Targeting/TargetingApi.cs Optional one-line reserve clarifying cast denials vs target-select denials (avoids mis-mapping event names).
client/README.md Short “Slice 3 telemetry (NEO-27)” pointer next to SelectionEvent section.
docs/decomposition/modules/documentation_and_implementation_alignment.md E1.M3 snapshot: NEO-27 telemetry hook sites landed (per team rule).
docs/decomposition/modules/E1_M3_InteractionAndTargetingLayer.md Optional one-line under telemetry: code hook pointers (target_selection_client.gd, lock store)—only if the module table still says hooks are TODO-only; keep register alignment.
docs/plans/NEO-27-implementation-plan.md Keep kickoff clarifications and resolved decisions synchronized with actual implementation choices.

Tests

File Action
client/test/selection_event_client_test.gd Change only if new observable behavior is added (e.g. new export or signal). If implementation is comments + optional print format only, no test change — manual QA: enable log_selection_events, tab/clear, confirm output contains target_changed.
docs/manual-qa/NEO-27.md Add explicit manual checks for target_changed log token, id-change-only emission behavior, and ability telemetry reserve documentation.

Server: No new tests required for comment-only / dev-trace placeholders unless we introduce a testable abstraction (out of scope).

Open questions / risks

Resolved (2026-04-26): Linear no longer lists NEO-24 as blocking NEO-27 (dependency removed on board). Resolved (2026-04-26): Keep ability telemetry reserve comments in client/scripts/main.gd for NEO-27; no placeholder script yet.

None otherwise.