fix(format-spec): use the link references ResolveRedirect accepts

[JorisOrangeStudio]

Description

The link spec advertises statamic://entry/<uuid>. Nothing in Statamic resolves that. Statamic\Routing\ResolveRedirect, which backs the link fieldtype, understands exactly four forms: entry::<id>, asset::<container>::<path>, @child, and a plain URL passed through untouched.

Type of Change

• 🐛 Bug fix
• ✨ New feature
• 🔧 Tool enhancement
• 📝 Documentation
• ♻️ Refactoring

Related Issue

None — found following the spec when writing a button link, which stored a value no route ever resolves.

Testing

• Tests pass (composer test)
• Code quality checks pass (composer quality)
• Tested manually with Statamic

tests/Unit/FieldFormatSpecTest.php — 2 cases. Verified against main: both fail there, both pass here. Full suite 1108 tests / 5612 assertions.

Environment

• Statamic: v6.31.0
• Laravel: v13.30.1
• PHP: 8.4.25

Checklist

• My code follows the project style
• I've added/updated tests if needed
• Tool responses follow the standard format

Notes

statamic:// is Bard syntax — link marks and image nodes go through Bard\LinkMark — and even there the form is statamic://entry::<id>, not statamic://entry/<uuid>.

Link defines no process(), so a value following the old spec is stored verbatim: no error at write time, and nothing visibly wrong in the CP field until someone clicks the link. The trap is now named in common_mistakes.

[sylvesterdamgaard]

Reviewed and approved on the substance — this just needs a rebase on main before I can merge it.

Five of the batch landed (#50, #49, #46, #51, #47), and #50 also appended to tests/Unit/FieldFormatSpecTest.php, so your two test blocks now conflict. Textual only. I can't push to the branch (maintainerCanModify is off), so a rebase from your side is the quickest path — ping me and I'll merge.

I checked every claim in the new spec against Statamic\Routing\ResolveRedirect rather than taking the description's word for it, since this PR is entirely assertions about what resolves:

• @child — handled explicitly, and it throws unless the parent is an Entry, so "only resolves when the field's parent is an entry" is right.
• entry:: / asset:: — the prefix loop is Str::startsWith($redirect, "{$linkType->handle()}::") over Link::types(), and the two handles registered by core are entry and asset (ExtensionServiceProvider:275-276). AssetLinkType::resolve() is Asset::find($id), so asset::images::brochures/2026.pdf is exactly right.
• statamic:// — falls through every branch to return $redirect verbatim. The old spec was telling clients to write an unresolvable value, so this is a real fix, not just wording.

One thing you might consider as a follow-up, not for this PR: the two handles are hardcoded in the spec, but Link::extend() means an addon can register more. Deriving the list from Link::types() would keep it honest on a site that has done so — and #46, now merged, is arguably the seam for that.