Design: optional local package icons for plugin identity #3

Decision and purpose

Installed plugins need optional author-supplied visual identity. Introduce it through the new amadeus.extension/v1 manifest value, preserving the frozen v0 format.

Implementation: protocol #4 and Host #255. Both remain Draft; no merge or release is authorized by this design record.

Contract

• v0 stays unchanged and rejects icon; existing v0 packages remain supported by the new Host.
• v1 permits an optional package-relative icon: bundled PNG/JPEG, matching signature, at most 1 MiB. No URL, absolute/traversing path or executable image format.
• The Host owns installed-package resolution, native decoding and the 1024 x 1024 bound, trusted renderer access, 36 px display and name-initial fallback.
• The canonical validator selects v0/v1 from an explicit allowlist. Unknown versions/fields remain rejected.
• Missing icons belong to P5, theme images to P4 and package commands to P3.
• Runtime contracts, Host API and SDK versions remain unchanged.

Compatibility and release gate

A v0-only Host rejects v1 even when no icon is declared. Its existing schema-before-engines validation may report invalid manifest; changing the required Host API cannot alter this old behavior. Authors must identify a v1-capable minimum application version in distribution notes.

Merge the reviewed protocol first, verify the Host pin is an ancestor of canonical main, and recheck copied source/hashes. The catalog's checker remains pinned to 1840c8e; no v1/icon packages enter the catalog before independent requalification.

Acceptance evidence

Canonical tests cover both versions, existing contributions, forbidden v0 icons, unknown fields/versions, bounded resources and error ownership. Host tests cover real v0/v1 wheel inspection/preparation, packaged-schema loading, native decoding, registry updates/removal, trusted IPC and visual fallback.