fix(agent): reject non-UUID AgentUuid on override + persisted paths

[ottobolyos]

Summary

Hardens the Agent meta-device UUID resolution slice added by #168 so malformed input never reaches the wire — closing the gap on both the operator-supplied override AND the persisted agent.information.json paths. The prior single-path validation left Path 2 open: a corrupted state file (or a pre-hardening agent version that wrote non-UUID content) would flow straight to the wire and fail every downstream MTConnect Part 1 XSD-validating consumer on typed enum/decimal DataItems.

Change

• New AgentUuidResolver.Resolve (public static, MTConnect.NET-Common) implements the three-path algorithm:
  • Path 1 — validated operator override wins;
  • Path 2 — validated persisted state wins over derivation;
  • Path 3 — deterministic UUID v5 derivation from ServiceName.
    Malformed input on Path 1 OR Path 2 logs a warning via a delegate hook (so MTConnect.NET-Common takes no hard dependency on NLog) and falls through to the next path. Raw values echoed to the warn log are pre-sanitized (CRLF stripped, truncated to 64 chars) as guards against log-injection and paste-in-wrong-field secret leakage.
• MTConnectAgentApplication.RunAgent routes through the shared resolver instead of hand-rolling the dual-if resolution. Collapses the two-branch shape that re-tested string.IsNullOrEmpty twice.
• DeterministicAgentUuid.TryValidate parameter renamed normalised → normalized per CONVENTIONS §1.0d-decies (AmE in committed code); XML-doc verbs updated to match. Positional / out var callers unaffected.
• Test fixtures brought forward — AgentUuidConfigOverrideTests + AgentUuidLongitudinalInvariantsTests now route their boot simulation through AgentUuidResolver.Resolve instead of inline replay, and their fixture literals are canonical RFC 4122 UUIDs (previously non-UUID strings that survived only because the inline replay omitted TryValidate — fake-green). Every fixture marked [NonParallelizable] with orphan-.bak.* sweep.

Test plan

• dotnet test tests/MTConnect.NET-Common-Tests/ — all AgentUuid*Tests.* GREEN on the full CI matrix.
• AgentUuidValidationTests covers: TryValidate low-level (null/whitespace/unparseable/canonical/normalization), malformed-override fresh-boot fall-through to derived, malformed-override with valid-persisted preserves-persisted, malformed-persisted with no-override falls through to derived (Path 2 hardening), non-canonical valid override normalized, persisted-adopted-on-second-boot, first-boot persists derived to disk.
• AgentUuidConfigOverrideTests + AgentUuidLongitudinalInvariantsTests continue to pin the config-override wins-over-persisted contract but now via the same code path production uses.
• Docs-site drift gate (docs.yml) — inherits pre-chore(ci): unblock master (docs drift, Scriban CVE, nav-title test) #205 drift on this PR's isolated head; the fix lives in chore(ci): unblock master (docs drift, Scriban CVE, nav-title test) #205 and cascades in once chore(ci): unblock master (docs drift, Scriban CVE, nav-title test) #205 merges. integration/all-fixes union at bfca1bd2 unions chore(ci): unblock master (docs drift, Scriban CVE, nav-title test) #205 + this PR and passes.

Commits (RED → GREEN):

1. test(common-tests): pin AgentUuid RFC 4122 contract on both resolution paths (RED) — compile-error RED per §1.0d-vicies-semel (tests reference AgentUuidResolver which lands in commit 2).
2. fix(agent): reject non-UUID AgentUuid on override AND persisted paths — introduces the resolver, wires RunAgent through it, renames normalised → normalized.

https://claude.ai/code/session_015FLSuNX8hZPFiTGtE8GYqH