fix(esp32): honor VCS platform refs instead of resolving IDF6 preview to stable SDK5 #1662

Context

During FastLED/FastLED#4773 validation with fbuild 2.5.37, the registered esp32dev_idf6 profile built successfully against SDK 5.5.5 despite requesting pioarduino's IDF6 VCS branch. A green compile therefore did not validate the requested SDK generation.

Repro from FastLED:

bash compile esp32dev_idf6 --examples Blink --max-failures 1

Generated project input:

[env:esp32dev_idf6]
platform = https://github.com/pioarduino/platform-espressif32.git#prep_IDF6
board = esp32dev
framework = arduino

Observed package-resolution output:

requested platform=https://github.com/pioarduino/platform-espressif32.git#prep_IDF6
resolved platform=platform-espressif32@stable
framework=esp32-arduino@3.3.11
ESP-IDF SDK=5.5.5

Second investigation checked the live branch manifest through GitHub's contents API: platform.json on prep_IDF6 reports version 61.04.00+develop, with framework archive https://github.com/espressif/arduino-esp32/archive/release/v4.0.x.zip. This differs from the resolved stable/Arduino3.3.11 stack. The branch is mutable; tests should pin fixtures or record the resolved commit.

Proposal

Honor the ESP32 platform repository ref and resolve its selected manifest/dependencies through the shared package resolver. Do not substitute stable metadata for a valid requested repository ref. If the requested preview stack is unsupported, return a specific error rather than report a successful build of another SDK generation.

Acceptance criteria

• RED: an offline VCS-ref fixture and the focused build repro show the requested manifest differs from the current stable fallback. Capture requested/resolved platform, framework, toolchain and SDK.
• GREEN: the selected VCS ref resolves its manifest and dependencies and builds against that stack. Pin/cache by repository commit identity; test that different refs cannot alias a stable payload.
• Unavailable refs and genuinely unsupported preview stacks produce explicit actionable errors before compilation, never a stable fallback.
• Existing archive/release URL pins continue to work.
• Build output/metadata includes actual resolved repository commit and SDK; FastLED can prove whether its IDF6 leg really tests IDF6.

Decisions

• This is an ESP32 VCS platform-ref resolution defect, distinct from the closed registry package-alias fix fix(esp32): honor registry-pinned framework packages #1492 and CH32V-specific VCS issue fix(ch32v): honor PlatformIO VCS platform source and package pins #1495.
• Keep this follow-up separate from FastLED's annotation/flash optimization; do not redesign FastLED build files to mask a resolver mismatch.
• Do not assert an internal root cause from the log alone. The resolver must be audited to find the stable substitution path.

Related issues

• meta: resolve PlatformIO package aliases and build requested stacks #1491 covers shared registry/archive/repository payload resolution, but is closed.
• feat(esp): fully implement real FL_NO_EXCEPT across all supported ESP platforms FastLED#4773 requires genuine SDK coverage or an explicit documented toolchain gap.