feat(adaptive-points): adaptive-path traversal SDK contracts (epic-029 F4)

[DanielKow]

What

Adds the SDK surface for Epic 029 · Feature 004 — Adaptive Path Traversal (design.md §3) to RocketWelder.SDK.AdaptivePoints, beside the existing IAdaptivePoint / IAdaptivePointService / GetAdaptivePoint. Contracts only — the host implements the service and handle, exactly as it does for IAdaptivePoint today.

Contracts added

Type	Role
IAdaptivePath	Live handle to one taught path, bound to the active robot, identity = start point's name. One behaviour: TraverseAsync(velocity, ct) → TraverseReport. Drives the robot start → mids → end by linear moves; does not adapt.
IAdaptivePathService	Robot-scoped read surface: Get(startName) / List(). No robot id — mirrors IAdaptivePointService.
ctx.GetAdaptivePath(startName)	Required wrapper on IProgramContext, twin to GetAdaptivePoint: returns the handle or throws when no path starts at that name.
TraverseReport	Returned, never thrown: Completed, StoppedAt (point name a failed/cancelled move stopped on, or null), and StartOffset / EndOffset as OffsetState.
OffsetState	Resolved(offset) vs Zero — mirrors the AdaptResult discriminated-record idiom so the operator reads full / partial / no correction (FR-2.5).

Notes

• Reuses the existing Velocity (from Devices.Robot) and Vector3<double> (from ModelingEvolution.Drawing); added a ProjectReference to RocketWelder.SDK.Devices.Robot for Velocity.
• Package bumped 1.0.0 → 1.1.0 (additive). Not published here — publishing is a separate, user-approved step after merge.
• Doc/XML style mirrors IAdaptivePoint / AdaptResult exactly. No TODOs, no magic defaults.
• Full solution builds clean (0 errors; no new warnings). No test project exists for this package, and these are pure contracts, so no tests were added.

🤖 Generated with Claude Code

[DanielKow]

Review — Wave 1 (SDK contracts), Epic 029 · Feature 004 Verdict: contracts are clean and conform to design.md §3. No code blockers. One MINOR (csproj version, inline) + one SHOULD release-process caveat (below). ### Design conformance (design.md §3) — ✅ - IAdaptivePath — identity = StartName; TraverseAsync(Velocity, CancellationToken) → Task<TraverseReport>; doc states "It traverses; it does not adapt." Mirrors IAdaptivePoint. ✓ - IAdaptivePathService — Get(startName) / List(), no robot id (robot-scoped). Mirrors IAdaptivePointService (correctly omits the point-only GetByTeachPoint). ✓ - ctx.GetAdaptivePath(startName) — required wrapper via GetRequiredDevice<T>, throws InvalidOperationException on miss. Twin of GetAdaptivePoint. ✓ - TraverseReport — Completed, StoppedAt, StartOffset/EndOffset. Returned, never thrown. StoppedAt as a point name (string?) is confirmed by test-scenarios S8 (StoppedAt=m2). ✓ - OffsetState — Resolved(Vector3<double>) / Zero, distinct even at numeric zero (FR-2.5). Mirrors the AdaptResult discriminated-union idiom (abstract record, private ctor, nested sealed records). ✓ Contracts only — no implementation logic leaked. Pure interfaces + records; the host implements. ✓ Build: RocketWelder.SDK.AdaptivePoints builds clean — 0 errors, 0 warnings in the new files (the 53 solution warnings are pre-existing CS1591/CS1574 in Vision/Hmi/Runtime). ✓ Standards (dotnet.md): file-scoped namespaces, nullable, full XML docs, IReadOnlyList<T> returns, idiomatic DU. ✓ ### Versioning — the host CAN consume this in Wave 2 (the feared blocker does not hold) I was asked to verify whether a hardcoded 1.1.0 would ship as the real version and block the host (which references 2.0.0). It would not, because publish is tag-driven: - .github/workflows/publish-csharp-nuget.yml derives VERSION from the pushed tag (refs/tags/…, stripping v/csharp-v), then dotnet build /p:Version=$VERSION + dotnet pack /p:PackageVersion=$VERSION. These override the csproj <Version>. - Every tag packs all packable projects at that one version, so AdaptivePoints publishes at the tag version regardless of the csproj number. - Canonical release path is the root release.sh → v* tags; latest is v2.3.0, so the next release (v2.4.0 / v2.3.1) is > 2.0.0 → host upgrade in Wave 2 works. ✅ ### [SHOULD] — release-process caveat for Wave 2 (real, actionable risk) There are two release scripts and two live tag lineages, and the workflow triggers on both (v*.*.* and csharp-v*.*.*): - root release.sh → v*, latest v2.3.0 - csharp/release.sh → csharp-v*, latest csharp-v1.1.42 If Wave 2's release is cut with csharp/release.sh, the next tag is csharp-v1.1.43, publishing AdaptivePoints at 1.1.43 < 2.0.0 — the host could not upgrade. Wave 2 must release via the root release.sh (→ v2.4.0). This is pre-existing infra, not introduced by this diff, so it's process guidance rather than a code change request. — .NET Reviewer

---

Tagged [SHOULD] by — Moderator. Independently reproduced and confirmed: root release.sh computes git tag -l 'v*.*.*' | sort -V | tail -1 → latest v2.3.0, tags v$VERSION; csharp/release.sh computes from csharp-v*.*.* → latest csharp-v1.1.42, tags csharp-v$VERSION. The publish workflow on.push.tags globs both lineages plus v*.*.*-preview*. Host pins 2.0.0 in 4 csprojs (3 × rocket-welder2 + adaptive-programs). A csharp-v1.1.43 publish (1.1.43 < 2.0.0) would not let the host upgrade; the root release.sh (→ v2.4.0 > 2.0.0, and carrying these new contracts) is required for Wave 2. No code change in this PR — this is a publish-gate directive recorded in the moderation log. Not a merge blocker.