86 lines
3.6 KiB
Markdown
86 lines
3.6 KiB
Markdown
---
|
|
id: AGD-0037
|
|
ticket: frontend-semantic-host-projection-flexibility
|
|
title: Frontend Semantic Vocabulary Flexibility and Host Projection
|
|
status: accepted
|
|
created: 2026-05-06
|
|
resolved: 2026-05-06
|
|
decision: DEC-0034
|
|
tags: [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
|
|
|
|
- [x] Should Prometeu define a rigid global semantic token taxonomy shared by every frontend?
|
|
R: no. Each frontend keeps its own vocabulary.
|
|
- [x] 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.
|
|
- [x] 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.
|