prometeu-studio/discussion/workflow/agendas/AGD-0037-frontend-semantic-host-projection-flexibility.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0037	frontend-semantic-host-projection-flexibility	Frontend Semantic Vocabulary Flexibility and Host Projection	accepted	2026-05-06	2026-05-06	DEC-0034	compiler compiler-general frontend semantics vscode host-projection lsp

Pain

The current discussion exposed an architectural tension:

• frontend semantic keys must remain frontend-owned and flexible,
• but VS Code prefers host-shaped semantic token categories and modifiers,
• and forcing frontend vocabularies into a rigid global taxonomy would collapse frontend ownership into host constraints.

If Prometeu treats VS Code semantic categories as the canonical semantic contract, the frontend loses semantic freedom and the wrong layer starts owning language meaning.

Context

Domain owner: compiler/general

This discussion extends DEC-0033 rather than replacing it. DEC-0033 already locked that visual themes are frontend-owned and hosts are adapters.

What remained implicit was how a frontend-owned semantic vocabulary should adapt to host capabilities when the host prefers a different semantic model.

The key clarification is:

• the frontend semantic vocabulary remains canonical,
• host adaptation is declarative projection,
• host projection does not become the canonical semantic contract.

Open Questions

• Should Prometeu define a rigid global semantic token taxonomy shared by every frontend? R: no. Each frontend keeps its own vocabulary.
• How should VS Code consume flexible frontend vocabularies without becoming the owner of semantic meaning? R: through a frontend-authored host projection for VS Code.
• Does this revise DEC-0033? R: it complements DEC-0033 by clarifying semantic vocabulary and host projection responsibilities.

Options

Option A - Canonicalize around VS Code token types

• Approach: Force frontends to express semantic meaning in a shared VS Code-shaped taxonomy.
• Pro: Simplifies host adaptation.
• Con: Makes the host model canonical and removes frontend semantic freedom.
• Maintainability: Poor. It solves adapter simplicity by weakening frontend ownership.

Option B - Keep frontend vocabularies canonical and add declarative host projection

• Approach: Let each frontend define its own semantic keys and publish host projection metadata that explains how a host such as VS Code should adapt those keys.
• Pro: Preserves frontend semantic ownership while keeping host adaptation mechanical.
• Con: Requires an additional contract layer.
• Maintainability: Strong. Ownership stays correct and adapters remain declarative.

Tradeoffs

Option A would make the current VS Code situation easier, but only by moving semantic authorship to the wrong layer.

Option B adds contract surface, but that surface is the correct one because it keeps the frontend canonical and makes host projection explicit rather than implicit.

Recommendation

Adopt Option B.

Frontend semantic keys remain canonical and flexible. Hosts such as VS Code consume a declarative projection authored by the frontend for that host.

Discussion

This discussion is intentionally narrow. It does not reopen the frontend-owned visual theme decision. It only clarifies that semantic vocabulary itself must also remain frontend-owned, and that host adaptation must be expressed as projection rather than normalization into a rigid shared taxonomy.

Resolution

Accepted on 2026-05-06.

Prometeu keeps frontend-owned semantic vocabularies flexible and introduces declarative host projection as the adaptation mechanism for hosts such as VS Code.