prometeu-studio/discussion/workflow/decisions/DEC-0034-frontend-semantic-host-projection-flexibility.md

id	ticket	title	status	created	accepted	agenda	plans	tags
DEC-0034	frontend-semantic-host-projection-flexibility	Frontend semantic vocabularies remain canonical and hosts consume declarative projections	accepted	2026-05-06	2026-05-06	AGD-0037	PLN-0072 PLN-0073 PLN-0074	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.