meta: resolve PlatformIO package aliases and build requested stacks #1491

Context

A platformio.ini can request platform = <platform>@<version> or platform_packages = <package>@<version>. fbuild currently accepts these registry-version forms, emits a warning, and builds with its own pinned packages. crates/fbuild-config/src/platform_packages.rs::ignored_version_pins says fbuild has no PlatformIO registry resolver. The warning fixed the silent failure reported in #1407, but it does not make the requested build reproducible or equivalent to PlatformIO.

The published ESP32-S3 comparison demonstrates the impact: bench/blink/platformio.ini requests espressif32@6.13.0; PlatformIO resolves Arduino-ESP32 2.0.17 and Xtensa GCC 8.4.0, while fbuild ignores that registry pin and locally resolves Arduino-ESP32 3.3.12 and Xtensa GCC 14.2.0. The benchmark comparison is tracked in #1489. Pre-unified pioarduino releases also need per-MCU registry toolchains (#1444).

This parent coordinates an audit of all supported platform families, not an assumption that each is affected. Findings should become native sub-issues only when an agent verifies a concrete ignored pin or package mismatch; clean/unsupported cases should be reported without filing noise.

Proposal

1. Inventory every supported platform family and the platform / platform_packages registry-version paths it accepts. For each family, compare the requested version with the resolved platform, framework, toolchain, and SDK package versions from a real fbuild build or a focused resolution test. Compare with PlatformIO's registry metadata where feasible.
2. File one focused child per independently actionable platform-family failure. Include a minimal platformio.ini, observed warning and resolved versions, the resolution code path, user impact, and a plausible fix boundary. Link existing issues rather than duplicate them.
3. Implement a real PlatformIO registry alias resolver for short and owner-qualified platform and platform_packages specs. Resolve valid exact pins and supported version requirements to the published platform/package archive URL and SHA-256; use the selected platform manifest, board/framework, host architecture, and explicit package overrides to resolve the compatible framework, SDK, and toolchain set. A server-side metadata alias service may cache and normalize PlatformIO registry responses while binaries remain PlatformIO-hosted. Never substitute a default or a different vendor release. Preserve working URL/archive overrides.
4. Make build and benchmark artifacts record requested and resolved package/toolchain versions so cross-version results are visible.

Shared core resolver and unit tests

• Put the generic PlatformIO package-spec parser, normalized request, resolved-payload/lock model, version and precedence rules, and structured errors behind a reusable fbuild-core API. It must not be gated by the current Platform enum or hard-coded ESP/ARM/AVR names: an unknown-but-valid owner/name@version can resolve its payload even if native build dispatch later reports no orchestrator. Keep network/download/extraction adapters in existing fbuild-packages-fetch; every platform orchestrator consumes the same resolved result. Do not add a new crate.
• The core API resolves registry aliases (short and owner-qualified; exact versions and supported ranges), local/remote archives, repository URLs/refs, and local package directories to a normalized source/payload identity. For registry files it records the selected host-specific URL and checksum; for a platform it parses platform.json and applies framework/toolchain/SDK requirements and explicit platform_packages precedence. Unsupported schemes or unavailable versions produce structured errors, never a default substitution.
• Add offline, table-driven core unit tests with fixture registry responses and platform manifests: each source form above; a synthetic platform name absent from the Platform enum; exact/range selection; host architecture; checksum/digest and cache-key identity; dependency and override precedence; malformed/unavailable inputs. Add a representative resolution fixture for every native platform family in its child issue. Unit tests must not depend on the live registry or downloaded compilers; focused integration/build repros remain separate.
• Treat any syntactically valid PlatformIO package path as a core payload-resolution request, independent of build-platform dispatch: short aliases (espressif32@6.13.0), owner-qualified aliases (platformio/espressif32@6.13.0), explicit type/owner/name paths, and registry/archive/repository/local-path sources must normalize to the same immutable payload identity when they identify the same artifact. Core must expose the resolved URL or local source, digest/ref, selected host file, and manifest dependency identities; unsupported native builds are a later, separate error.
• Require a shared, offline core test matrix with one representative registry/platform-manifest fixture for each supported native family (ESP32, ESP8266, AVR/megaAVR, ARM families, CH32V), plus a synthetic unknown family. For each fixture assert the exact platform, framework, SDK and toolchain payloads that apply; host filtering, explicit override precedence, no default substitution, malformed/unavailable-path errors, and stable cache identity. Children add adapter/build tests, but must not duplicate or bypass generic lookup in their orchestrators.

Acceptance criteria

• RED: focused repros/tests for every confirmed child show that a supported registry pin currently yields a successful build with a different resolved package stack (or document the exact related failure).
• GREEN: valid published platform = name@version and platform_packages = name@version aliases for every supported native family resolve the requested platform/package versions, select compatible host-specific dependencies, and build with that stack. Cover exact pins, owner-qualified and short aliases, and supported semver requirements. A missing version, unsupported host, or truly unsupported package fails before compilation; refusing a valid supported alias is not completion.
• Resolved platform, framework, toolchain, and SDK versions are visible in build output or machine-readable metadata; benchmark comparisons validate matching stacks or label/exclude cross-version comparisons.
• URL/archive overrides continue to work. Tests cover cache reuse, host architecture, and platform-specific package layouts; each confirmed child has focused RED → GREEN evidence.
• All supported platform families are inventoried, with positive child issues attached natively to this parent and negative findings summarized in the parent discussion.
• RED → GREEN core unit evidence: a failing test first shows a valid generic registry/path spec currently becomes None, a warning, or a default package; after the shared resolver lands, that same fixture yields the exact normalized payload and dependent package identities. A synthetic unknown platform must resolve payload metadata without claiming native build support.
• Every supported-platform child has a RED failing core resolution assertion before its fix, then a GREEN assertion against the exact expected payload URL/checksum or VCS ref and dependency identities. The common core matrix passes offline on CI, without installed PlatformIO tools or downloaded compilers; family-specific build tests verify the adapter consumes those results.

Required alias contract

• Example: espressif32@6.13.0 / platformio/espressif32@6.13.0 must resolve to PlatformIO's platformio/platform/espressif32 version 6.13.0, not pioarduino stable. The registry metadata supplies the archive URL and SHA-256; the selected platform.json supplies package requirements. The metadata alias service is optional infrastructure, not a license to substitute a different stack.
• Resolve tool and framework files for the actual host/system, apply platform_packages override precedence, verify checksums, and key caches by the resolved package identity and digest. Emit the requested and resolved identities in build/benchmark metadata.
• Early errors are guardrails for unavailable or unsupported inputs. This parent is not complete until known-valid PlatformIO aliases build with their requested compatible stack across supported native families.

Decisions

• Treat ignored registry pins as a correctness/reproducibility problem, priority P1: warnings are useful but cannot fulfill an explicit build-version request.
• Coordinate by platform family so distinct package sources and toolchain layouts remain independently actionable; use one child for closely related boards sharing the same resolver, not one issue per board.
• Do not infer that GCC 14 alone caused the ESP32-S3 timing gap. The verified problem is a mismatched requested/resolved stack; a controlled same-stack benchmark remains required (fix(bench): align ESP32-S3 toolchains and explain cold-build gap #1489).
• Include both platform and platform_packages registry-version forms, but keep URL overrides as a separate already-supported path.
• Core ownership: define the generic spec/resolved-payload contract in fbuild-core, with fetch/extract in fbuild-packages-fetch, because these are the existing shared and package-transport boundaries; platform-specific orchestrators only adapt the resolved build recipe.

Related issues

• A pinned platform version is silently ignored — in platform and in platform_packages #1407 fixed the warning for silently ignored version pins; it did not implement registry resolution.
• fix(bench): align ESP32-S3 toolchains and explain cold-build gap #1489 tracks the ESP32-S3 benchmark mismatch and should be a child of this parent.
• ESP32: provision per-MCU registry toolchains so pre-unified platform pins (pioarduino 51.x) actually build against their pin #1444 tracks legacy pioarduino per-MCU registry toolchains and should be a child of this parent.

Testing gate: core resolves any generic PlatformIO path

• Implement and exercise a public fbuild-core resolver that accepts a PlatformIO path/spec without consulting the native Platform enum or any ESP/ARM/AVR-specific code. A syntactically valid unknown platform/package must resolve its payload metadata; lack of a native compiler adapter is a separate, later error.
• RED → GREEN unit tests first: a valid pinned path that currently becomes a warning, None, or a default must initially fail an exact-payload assertion. The same test must pass after the shared core fix. Each platform child contributes at least one failing-then-passing fixture to this shared core suite, in addition to adapter tests.
• Table-drive offline fixtures for ESP32, ESP8266, AVR and megaAVR, each supported ARM family, CH32V, and a synthetic unknown family. Cover short names, owner-qualified names, explicit type/owner/name paths, exact pins and supported version ranges, registry packages, HTTP(S) archives, repository URLs/refs, and local paths. Equivalent spellings of one artifact must produce the same normalized payload identity.
• For each fixture assert the selected platform/package version, exact host-specific URL and SHA-256 (or immutable VCS ref/local content identity), manifest-derived framework/SDK/toolchain requirements, explicit platform_packages precedence, and a stable cache key that changes when payload content changes. Test multiple host systems and reject unsupported hosts.
• Negative unit cases must reject malformed/ambiguous paths, missing versions, unsupported schemes, checksum mismatches, and incompatible or unavailable dependencies with structured errors before compilation. Never silently use a default or different release for a valid pin.
• Core unit tests run offline in CI with fixture metadata: no live registry, PlatformIO installation, or compiler downloads. Separate family adapter/build tests prove the resolved core payload is actually consumed and requested versus resolved identities are visible. A passing family test that bypasses core does not satisfy this gate.