prometeu-studio/discussion/lessons/DSC-0034-frontend-semantic-host-projection-flexibility/LSN-0048-frontend-owned-semantic-vocabularies-with-declarative-host-projection.md

id	ticket	title	created	tags
LSN-0048	frontend-semantic-host-projection-flexibility	Frontend-Owned Semantic Vocabularies with Declarative Host Projection	2026-05-07	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.