Project-M/.claude/skills/dots-dev/references/validation-harness.md

Validation harness — driving Unity Play mode safely from MCP

Consolidates the Play-mode validation lore that used to live only in machine-local memories (screenshot-pause bug, sleep-poll ban, execute_code traps, headless-run flakiness) plus the proven server-inject harness. Load when running Phase 6 (verify ladder) or any live diagnosis. Committed + in-repo: this is the cross-machine home of these rules.

Ground rules (violating these produces MISDIAGNOSES, not just failures)

1. Never Thread.Sleep / sleep-poll inside execute_code. It runs on the main thread — it freezes the entire sim, and state read "after waiting" is state from a FROZEN world. This manufactured the retracted WasAllReady "save deadlock" (2026-07-06). Spread observation across separate MCP calls instead — each round-trip gives the sim hundreds of ms to advance.
2. The bridge's game-view capture PAUSES the editor (EditorApplication.Step). Check isPaused first, unpause after any bridge capture. Prefer ScreenCapture.CaptureScreenshot(path) inside execute_code — async, lands at frame end; Read the PNG on the NEXT MCP call (the round-trip covers it).
3. An unfocused editor throttles Edit mode to near-idle (MCP looks hung; test INIT stalls — pass init_timeout=120000) and can leave a STALE Burst binary after Bursted query-set edits. Ask the operator to focus Unity for compile/test/Burst-heavy phases. Application.runInBackground only helps in Play mode.
4. Play-enter resets static presentation configs via [RuntimeInitializeOnLoadMethod] — a value poked via execute_code does not survive the next play-enter. Conversely: if a whole presentation slice is silent, FIRST probe its static config (return ProjectM.Client.XFeelConfig.Enabled;) before theorizing structurally — the 2026-07-07 harvest-feedback bug was found by that one read after a plausible transform-hierarchy hypothesis proved wrong.

execute_code traps

• Runs as a method body: no using directives (parsed as statements) — fully-qualify every type.
• Identify worlds by world.Name == "ServerWorld"/"ClientWorld" (flags overlap a shared Game bit).
• Type.GetMethod(name, flags) throws AmbiguousMatchException on overloaded methods (EntityManager generics, netcode statics) — iterate GetMethods() and filter by name/param-count, or call concrete generics directly in compiled code.
• Rukhanka ParameterValue is a union — read floatValue/boolValue per the parameter type.
• Return a built string (StringBuilder) — it's the only channel out.

The server-inject harness (validate replicated presentation WITHOUT gameplay driving)

Proven 2026-07-07 (NodeFeedbackSystem). Validates a replicated-state → client-presentation path end-to-end in ~4 MCP calls, no expedition run, no player positioning:

1. Spawn (server world): query the ghost prefab (ComponentType + EntityQueryOptions.IncludePrefab, pick the one with Prefab), Instantiate, then em.GetComponentData<LocalTransform>(prefab).WithPosition(playerPos + offset) — never LocalTransform.FromPosition (resets Scale=1; Scale replicates → consistent-but-wrong). Find the player via KinematicCharacterBody + LocalTransform.
2. Defeat relevancy: a region-tagged ghost spawned at base gets culled from base players — em.SetComponentData(inst, new RegionTag { Region = 0 /* Base */ }) in the same call.
3. Inject state changes server-side (SetComponentData on the replicated component) in one call; read the client in the NEXT call (round-trip ≥ several ticks — replication has happened).
4. Assert numerically, then screenshot. e.g. client PostTransformMatrix.c0.x vs the expected lerp(min, 1, frac) and child LocalToWorld scale (math.length(ltw.c0.xyz)) vs bakedScale × ptm. Numbers prove the math; the screenshot proves it renders (both matter — see visual limits below).

Ghost/LEG inspection idioms: em.GetBuffer<LinkedEntityGroup>(root); render children = LEG entries with MaterialMeshInfo (the root usually has none); parenting = Parent component; a baked child's uniform authoring scale lands in LocalTransform.Scale (non-uniform → its own PostTransformMatrix). A root PostTransformMatrix DOES propagate into parented children's LocalToWorld (verified live on 6.5.0).

Headless expedition-run driving (flaky — know the failure modes)

The specific nouns below (PlayerReady, expedition launch, respawn-reset) are co-op-Hades-era and become salvage under the LANTERN pivot (DR-048_Lantern_Adoption_Full_Pivot) — they will be re-meaned to the descent lifecycle (muster → Bell → pockets) when that lands. The harness patterns (server-inject, the EditorApplication.update guardian, capture-in-the-same-call) are direction-agnostic and stay valid.

• Launch by setting server PlayerReady=1 from clean Staging. Post-abort re-launch is intermittent — a clean Play restart launches reliably on the first ready; re-readying after an abort may not.
• An AFK player dies to the swarm in ~15 s and Health resets to the class value on respawn — a SetComponentData HP buff does NOT stick across respawn; the run then aborts (0 expedition players → Returning) and tears down the room.
• Therefore: capture evidence in the SAME execute_code call that first detects the condition (e.g. enemies>0) — a separate "then screenshot" round-trip loses the window.
• Multi-sample observations (movement deltas, before/after) that can't fit one call: install an EditorApplication.update guardian delegate (proven 2026-07-09, enemy-backstop smoke). The closure runs every editor frame: it can out-race damage (Health.Current = Max per frame — beats the respawn-reset trap above), park the player, take timed snapshots, and stash results in EditorPrefs (survives across execute_code calls — statics do NOT). Always: wrap the body in try/catch that UNSUBSCRIBES on error, add a hard timeout unsubscribe (~90 s), self-unsubscribe when done, and delete the EditorPrefs keys after reading them.
• Prefer the server-inject harness above whenever the question doesn't actually require a live run.

Visual/asset verification limits

• A dark/stylized frame masks material bugs — verify VALUES: shader.GetPropertyType(idx)-guard before GetColor/GetFloat/GetTexture (e.g. S_General._BaseColorMultiply is a float; GetColor returns black).
• Skinned meshes lie to readers: WorldRenderBounds/bone transforms return the bind-pose AABB, not the deformed pose — deformed-pose visual bugs need the operator's eyes (or a screenshot), not entity reads.
• Body tint/flash validation: drive the stock EG URPMaterialPropertyBaseColor override on the render (LEG) children; verify on the LOCAL player (persistent, centered) rather than a transient enemy.
• Forcing an animation pose: disable the drive system, write params via AnimatorParametersAspect; measure ground-contact via feet-Y only on non-deformed geometry.

Input-path validation (07-21, the auto-recast false negative)

• A guardian window must OUTLIVE the period it judges. Frames ≠ ticks: an unfocused editor can run FASTER than 60 fps, so a 500-frame watch can end BEFORE a 7 s cooldown does. The morning "sim is clean" verdict was a false negative for exactly this; the 2000-frame re-run caught a recast at every cooldown reopen. Size the window in TICKS of the judged period × 2, converted generously.
• DebugInputInjectionSystem writes the COMPONENT — it can never reproduce wire-semantics bugs. To exercise the real gather → copy-layer → command-buffer path headless, queue synthetic device events: StateEvent.From(Keyboard.current, out var ev); InputControlExtensions.WriteValueIntoEvent<float>(kb.digit1Key, 1f, ev); InputSystem.QueueEvent(ev); (+ a 0f release event). Works unfocused with runInBackground.
• Wire truth: InputEvent counts ACCUMULATE across commands (the per-frame gather reset never reaches the buffer). Test fixtures that push InputBufferData<PlayerInput> must model that: press = count STEP at one tick, and the stepped count PERSISTS in every later entry — a "release = count 0" entry is a wire-impossible shape that hides the ever-pressed class of bug (and double-fires a delta gate).

EditMode fixtures for prediction-gated systems (07-21, AbilityFireSystemConeTests)

• NetworkTime.Flags is INTERNAL — a system gated on IsFirstTimeFullyPredictingTick silently no-ops in any plain test world (default Flags = 0). Fixture fix: box the struct + typeof(NetworkTime).GetField("Flags", NonPublic|Instance).SetValue(boxed, NetworkTimeFlags.IsInPredictionLoop | IsFirstTimeFullyPredictingTick). Test-only; never reflect internals in shipped code.
• Input-buffer presses: an InputBufferData<PlayerInput> entry with a set InputEvent keeps answering GetDataAtTick for every later tick — it re-fires the moment a cooldown re-opens (the MeleeComboTests C6 lesson, buffer-shaped). Always push a press at T and a release (default command) at T+1.
• Damage paths gated WorldUnmanaged.IsServer() need new World(name, WorldFlags.Game | WorldFlags.GameServer).

Test-run mechanics

• run_tests(mode="EditMode", assembly_names=["ProjectM.Tests.EditMode"]) → poll get_test_job (wait_timeout=60). Unfocused editor: init_timeout=120000 and retry once before diagnosing.
• A test count LOWER than expected with zero failures = tests not discovered (raw-written .cs without refresh_unity scope=all mode=force), not a pass.