113 lines
4.4 KiB
Markdown
113 lines
4.4 KiB
Markdown
---
|
|
id: DEC-0034
|
|
ticket: frontend-semantic-host-projection-flexibility
|
|
title: Frontend semantic vocabularies remain canonical and hosts consume declarative projections
|
|
status: accepted
|
|
created: 2026-05-06
|
|
accepted: 2026-05-06
|
|
agenda: AGD-0037
|
|
plans: [PLN-0072, PLN-0073, PLN-0074]
|
|
tags: [compiler, compiler-general, frontend, semantics, vscode, host-projection, lsp]
|
|
---
|
|
|
|
## Decision
|
|
|
|
Prometeu SHALL keep semantic vocabularies frontend-owned and canonical.
|
|
Hosts such as VS Code SHALL consume declarative host projection data authored by the frontend instead of forcing frontend semantic keys into a rigid shared host taxonomy.
|
|
|
|
This decision locks the following normative points:
|
|
|
|
1. Each frontend MUST remain free to define its own semantic keys.
|
|
2. Prometeu MUST NOT introduce a rigid global semantic token taxonomy as the canonical contract for all frontends.
|
|
3. Host-facing semantic adaptation MUST happen through frontend-authored host projection metadata.
|
|
4. Host projection metadata MUST be declarative and MUST NOT become the canonical semantic vocabulary.
|
|
5. VS Code adaptation MUST consume the frontend semantic vocabulary plus its VS Code projection, not reinterpret semantic meaning ad hoc inside the extension.
|
|
|
|
## Rationale
|
|
|
|
The current stack already establishes frontend ownership over visual themes.
|
|
Without this complementary rule, semantic vocabulary itself could still drift toward host ownership because VS Code prefers a different semantic model than a frontend may naturally publish.
|
|
|
|
If the repository made VS Code token categories canonical, it would:
|
|
|
|
1. collapse frontend semantic freedom,
|
|
2. move semantic authorship into the host layer,
|
|
3. and make frontend evolution hostage to one specific adapter model.
|
|
|
|
Declarative host projection preserves the correct ownership boundary:
|
|
|
|
1. frontend defines semantic meaning,
|
|
2. frontend also defines how a given host should project that meaning,
|
|
3. host adapters translate mechanically.
|
|
|
|
## Technical Specification
|
|
|
|
### 1. Canonical Semantic Vocabulary
|
|
|
|
The canonical semantic vocabulary for a document language MUST live in that frontend's contract surface.
|
|
|
|
This implies:
|
|
|
|
1. semantic keys remain frontend-owned,
|
|
2. semantic keys MAY vary significantly between frontends,
|
|
3. semantic keys MUST NOT be rewritten into a mandatory repository-wide host-shaped taxonomy.
|
|
|
|
### 2. Host Projection Contract
|
|
|
|
Frontend metadata MUST evolve to support host projection descriptors.
|
|
|
|
At minimum, a host projection descriptor for VS Code MUST be capable of expressing:
|
|
|
|
1. which canonical semantic key is being projected,
|
|
2. which VS Code semantic token type should receive that key,
|
|
3. which VS Code semantic token modifiers, if any, should accompany that projection,
|
|
4. any fallback behavior needed when the host cannot represent the frontend key exactly.
|
|
|
|
The host projection descriptor MAY support other hosts later, but the first required host projection is VS Code.
|
|
|
|
### 3. Ownership Rules
|
|
|
|
Ownership SHALL be:
|
|
|
|
1. frontend owns semantic keys,
|
|
2. frontend owns host projection metadata,
|
|
3. LSP transports both,
|
|
4. the host adapter translates both.
|
|
|
|
The extension MUST NOT become the place where semantic meaning is hand-mapped or reauthored as code-driven policy.
|
|
|
|
### 4. Relationship to DEC-0033
|
|
|
|
This decision complements `DEC-0033`.
|
|
|
|
`DEC-0033` remains normative for:
|
|
|
|
1. frontend-owned visual theme contracts,
|
|
2. frontend-owned theme variants,
|
|
3. host adapter responsibilities for visual rendering.
|
|
|
|
This decision adds the semantic vocabulary clarification that `DEC-0033` left implicit:
|
|
|
|
1. semantic vocabularies remain frontend-owned and flexible,
|
|
2. host adaptation is projection, not normalization.
|
|
|
|
### 5. VS Code Adapter Rule
|
|
|
|
For VS Code specifically:
|
|
|
|
1. the extension MUST consume frontend-owned semantic keys,
|
|
2. the extension MUST consume frontend-authored VS Code projection metadata,
|
|
3. the extension MUST apply that projection mechanically,
|
|
4. the extension MUST NOT force every frontend into a single rigid shared semantic taxonomy to satisfy VS Code.
|
|
|
|
## Constraints
|
|
|
|
1. No plan derived from this decision may replace frontend semantic keys with a mandatory global host taxonomy.
|
|
2. Any plan touching VS Code semantic adaptation MUST include declarative host projection support.
|
|
3. Any plan touching LSP transport for semantic vocabularies MUST preserve frontend canonical keys.
|
|
4. This decision MUST be treated as complementary to `DEC-0033`, not as a rollback of frontend-owned theming.
|
|
|
|
## Revision Log
|
|
|
|
- 2026-05-06: Initial accepted decision from AGD-0037.
|