prometeu-studio/discussion/workflow/plans/PLN-0074-vscode-semantic-host-projection-adapter.md

id	ticket	title	status	created	completed	tags
PLN-0074	frontend-semantic-host-projection-flexibility	VS Code Semantic Host Projection Adapter	done	2026-05-06	2026-05-06	vscode extension frontend semantics host-projection adapter

Objective

Make the VS Code extension consume frontend-authored semantic host projection metadata mechanically so semantic highlighting behavior no longer depends on extension-owned assumptions about frontend semantic key names.

Background

DEC-0034 makes the frontend semantic vocabulary canonical and requires VS Code adaptation to follow frontend-authored projection metadata rather than an extension-owned taxonomy. DEC-0033 already moved visual theme ownership into frontend-authored runtime payloads; the semantic adapter must now follow the same model.

The current extension still contains assumptions about semantic token naming and package-level declarations that do not fully reflect frontend-authored projection data.

Scope

Included

• Consume semantic host projection payload from the LSP handshake.
• Translate frontend-authored VS Code projection descriptors into the extension's semantic token registration and runtime theme application flow.
• Reduce extension-owned semantic assumptions to the minimum static structure the VS Code platform requires.
• Add tests or verification hooks that prove the adapter follows frontend-authored projection data mechanically.

Excluded

• Inventing or redefining canonical semantic meaning inside the extension.
• Reworking compiler semantic classification beyond consuming the delivered keys and projections.
• Solving projection for non-VS Code hosts.

Non-Goals

• Making the extension the owner of semantic taxonomy policy.
• Hardcoding PBS-specific semantic mapping logic as the authoritative source.
• Guaranteeing a perfect one-to-one rendering match with Studio for every frontend key.

Execution Steps

Step 1 - Update extension-side semantic projection models

What: Add extension-side runtime shapes for the transported semantic projection payload. How: Extend the VS Code extension client code so it can read and store:

1. canonical frontend semantic keys,
2. VS Code projection entries per key,
3. fallback metadata if present,
4. any language-scoped identity needed to apply the projection safely.

These runtime shapes MUST reflect transported frontend-authored metadata rather than a hand-maintained extension mapping table. File(s): tools/vscode-extension/src/**, generated out/** mirror as needed.

Step 2 - Apply projection mechanically in the semantic adapter path

What: Make the extension derive VS Code-facing semantic behavior from the transported projection. How: Update extension logic so semantic token registration, selectors, and any runtime semantic color rule generation consume the frontend-authored projection entries. The adapter MUST treat missing projection data as a fallback condition, not as permission to reauthor semantic meaning broadly in extension code. File(s): tools/vscode-extension/src/extension.ts, related extension helper modules if introduced, generated out/** mirror as needed.

Step 3 - Minimize static package-level semantic assumptions

What: Reduce static package.json semantic declarations to the minimum platform-required scaffolding. How: Audit the extension manifest and runtime so static declarations remain only where VS Code requires them structurally. Any semantic mapping policy that can be expressed by frontend-authored projection data MUST move out of the manifest and into runtime translation logic. File(s): tools/vscode-extension/package.json, tools/vscode-extension/src/**.

Step 4 - Lock adapter behavior with tests and verification

What: Prevent regression toward extension-owned semantic policy. How: Add tests or targeted verification code that assert:

1. the adapter reads frontend-authored projection payloads,
2. semantic rules derive from projection data rather than hardcoded PBS assumptions,
3. fallback paths stay bounded and explicit,
4. frontend projection updates do not require extension semantic remapping edits for ordinary token adjustments.

File(s): extension test surfaces if present, otherwise targeted runtime assertions and documented manual verification paths.

Test Requirements

Unit Tests

• Validate parsing of semantic projection payloads from the initialize response.
• Validate transformation from projection entries into VS Code semantic token rule inputs.

Integration Tests

• If extension test infrastructure exists, verify that a mock initialize payload drives semantic adapter behavior without code-level remapping tables.

Manual Verification

• Reload the extension and inspect runtime behavior with a PBS project to confirm semantic highlighting is driven by transported projection data.
• Confirm that a frontend-authored projection change would only require frontend/LSP updates, not new semantic mapping logic in the extension.

Acceptance Criteria

• The extension consumes canonical semantic keys and VS Code projection metadata from the LSP handshake.
• Semantic adapter behavior derives mechanically from transported projection data.
• Static extension manifest assumptions are reduced to platform-required scaffolding.
• The extension no longer acts as the authoritative source of frontend semantic mapping policy.

Dependencies

• DEC-0034 accepted and normatively locked.
• PLN-0073 completes LSP transport of semantic host projection metadata.
• DEC-0033 dynamic visual theme translation remains in place and coherent with semantic adaptation.

Risks

• VS Code manifest constraints may still require some static declarations, and those boundaries must stay explicit.
• Weak fallback rules could accidentally recreate extension-owned semantic policy.
• Failure to update generated extension output alongside source would leave the runtime out of sync in the current local environment.