91 lines
3.8 KiB
Markdown
91 lines
3.8 KiB
Markdown
---
|
|
id: LSN-0048
|
|
ticket: frontend-semantic-host-projection-flexibility
|
|
title: Frontend-Owned Semantic Vocabularies with Declarative Host Projection
|
|
created: 2026-05-07
|
|
tags: [compiler, compiler-general, frontend, semantics, vscode, host-projection, lsp]
|
|
---
|
|
|
|
## Context
|
|
|
|
Prometeu had already established that frontend-owned visual themes should remain canonical.
|
|
The remaining semantic risk was subtler: VS Code prefers host-shaped token categories, and that pressure could easily turn the host taxonomy into the real source of semantic truth.
|
|
|
|
This discussion closed that gap by making semantic ownership explicit:
|
|
|
|
- the frontend keeps the canonical semantic vocabulary,
|
|
- host adaptation is additional metadata,
|
|
- and the adapter translates mechanically instead of inventing semantic policy.
|
|
|
|
## Key Decisions
|
|
|
|
### Keep Frontend Semantic Keys Canonical
|
|
|
|
**What:**
|
|
Each frontend remains free to define and evolve its own semantic keys, and those keys stay canonical across the stack.
|
|
|
|
**Why:**
|
|
Semantic meaning belongs to the language frontend, not to a single host's preferred category system.
|
|
|
|
**Trade-offs:**
|
|
Adapters must handle more varied vocabularies, but that is the correct cost of preserving frontend ownership.
|
|
|
|
### Add Declarative Host Projection Instead of Global Normalization
|
|
|
|
**What:**
|
|
The frontend now authors host projection metadata describing how canonical semantic keys should map into VS Code token types, modifiers, and fallbacks.
|
|
|
|
**Why:**
|
|
Hosts still need a practical adaptation path, but that adaptation should be explicit projection data rather than a hidden normalization rule.
|
|
|
|
**Trade-offs:**
|
|
The contract grows an extra layer, but it stays declarative and prevents semantic meaning from being reauthored inside the adapter.
|
|
|
|
### Keep LSP and the Extension Mechanical
|
|
|
|
**What:**
|
|
LSP transports canonical keys plus projection metadata, and the VS Code extension consumes both mechanically.
|
|
|
|
**Why:**
|
|
If either layer starts hand-mapping semantic meaning, the host stack becomes the de facto author of language semantics.
|
|
|
|
**Trade-offs:**
|
|
The transport and adapter need clearer model shapes, but their responsibilities stay cleaner and more reusable.
|
|
|
|
## Patterns and Algorithms
|
|
|
|
### Pattern: Canonical Vocabulary Plus Per-Host Projection
|
|
|
|
The stable flow is:
|
|
|
|
1. frontend defines semantic keys,
|
|
2. frontend defines host projections for those keys,
|
|
3. LSP transports canonical keys and projection data together,
|
|
4. the host adapter applies the projection without reinterpretation.
|
|
|
|
### Pattern: Mechanical Translation with Explicit Fallbacks
|
|
|
|
Projection metadata should say not only the preferred host token type, but also the fallback when the host cannot represent the frontend key exactly.
|
|
That keeps fallback behavior visible and reviewable instead of implicit in adapter code.
|
|
|
|
## Pitfalls
|
|
|
|
- Do not collapse frontend semantic keys into a repository-wide host taxonomy.
|
|
- Do not hide semantic policy inside the VS Code extension just because the platform has its own token vocabulary.
|
|
- Do not transport only host-shaped token types and discard canonical frontend identity.
|
|
- Do not confuse projection metadata with the canonical semantic contract itself.
|
|
|
|
## References
|
|
|
|
- `DEC-0034` Frontend semantic vocabularies remain canonical and hosts consume declarative projections
|
|
- `PLN-0072` Frontend Semantic Host Projection Contract
|
|
- `PLN-0073` LSP Semantic Host Projection Transport
|
|
- `PLN-0074` VS Code Semantic Host Projection Adapter
|
|
- `DEC-0033` Frontend-owned visual theme spec as canonical presentation contract
|
|
|
|
## Takeaways
|
|
|
|
- Semantic ownership stays with the frontend even when the host prefers a different taxonomy.
|
|
- Host projection is the right adaptation mechanism; global normalization is not.
|
|
- LSP and host adapters stay healthier when they translate declaratively instead of authoring semantic meaning.
|