design: give the two .lnk roles distinct extensions #1369

Summary

.lnk currently serves two roles with different consumers, guarantees, and formats. Both parsers now accept both spellings (#1362, FastLED/FastLED#3990), so nothing is broken — but the ambiguity remains, and it is the kind that produces confident wrong edits.

Spun out of #1357, whose concrete work is complete.

The two roles

They are not competing drafts of one thing. The runtime form has to be parseable on an MCU, where fl::parse_lnk is deliberately allocation-light and there is no JSON parser worth carrying. The build-time form needs a mandatory digest because the resolver caches by content.

Why the shared extension is a hazard

It reads as one concept, so people normalize toward whichever form they met first. That already happened once, in FastLED/FastLED#4012: converting examples/AudioUrl/data/track.mp3.lnk to fbuild's JSON schema looked like tidying, and produced

tests/fl/asset/asset.cpp:108: { == www.soundhelix.com

because fl::parse_lnk took { as the URL. A test caught it. A sketch author gets a silently wrong URL instead.

Recommendation

Give the roles distinct extensions — keep .lnk for the runtime asset link, and use something else for build-time blob pointers — rather than converging the formats.

The alternative, converging on JSON, means putting a JSON parser in the MCU runtime for no user-visible benefit. Converging on text means giving up the mandatory digest that fbuild's content-addressed cache depends on. Distinct extensions cost one rename and make the mistake above impossible to express.

Open questions

1. What to call the build-time one. .blob, .fetch, .remote — something that does not read as a generic "link".
2. Migration: fbuild lnk add writes the new extension; existing files keep working since both parsers are tolerant. Deprecation window?
3. Does assets.json (multi-asset manifest, parsed by asset_scanner.py) fold into whichever the build-time form becomes?

Related

• research: normalize the .lnk format — two incompatible variants exist today #1357 — the normalization work, complete
• feat(lnk): accept the text-format .lnk alongside JSON #1362, feat(ci): fold all asset declaration parsing into one scanner FastLED#3990 — tolerant parsers on both sides
• fix(examples): give AudioUrl's .lnk a verifiable digest FastLED#4012 — the mistake this would prevent