prometeu-studio/discussion/workflow/plans/PLN-0073-lsp-semantic-host-projection-transport.md

id	ticket	title	status	created	completed	tags
PLN-0073	frontend-semantic-host-projection-flexibility	LSP Semantic Host Projection Transport	open	2026-05-06		lsp compiler frontend semantics host-projection vscode protocol

Objective

Transport canonical frontend semantic vocabulary and frontend-authored VS Code host projection metadata through the Prometeu LSP boundary without normalizing semantic meaning inside the transport layer.

Background

DEC-0034 requires LSP to carry both canonical frontend semantic keys and frontend-authored host projection metadata, while preserving the ownership boundary between frontend semantics and host adaptation. DEC-0033 already introduced frontend-authored visual themes through the LSP handshake; semantic host projection must now follow the same ownership model.

Scope

Included

• Extend LSP-facing baseline message models to carry semantic host projection metadata.
• Update the compiler-backed language service bridge to resolve and expose that metadata from frontend definitions.
• Update the LSP protocol mapper to publish the transported metadata to the VS Code extension.
• Add tests that prove canonical keys and projection metadata are both preserved across transport.

Excluded

• Defining the compiler-general projection contract itself.
• Applying the projection inside the VS Code extension.
• Redesigning semantic token classification logic beyond what is needed to expose projection metadata.

Non-Goals

• Performing semantic normalization inside the LSP layer.
• Collapsing frontend semantic keys into host token types in baseline message models.
• Introducing host-specific semantic rules into lsp-api that belong to frontend metadata.

Execution Steps

Step 1 - Extend baseline transport models for semantic projection

What: Add baseline message shapes that can carry semantic host projection metadata. How: Evolve LSP-facing DTOs so the server description or related handshake payload can transport:

1. frontend language identity,
2. canonical frontend semantic keys,
3. one or more host projection entries for VS Code,
4. any fallback metadata required by the projection contract.

The transport model MUST preserve canonical frontend keys explicitly rather than flattening everything into host token types. File(s): prometeu-lsp/prometeu-lsp-api/src/main/java/**, prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/**.

Step 2 - Resolve transport payload from compiler frontend metadata

What: Make the language service bridge expose semantic host projection metadata from the frontend contract. How: Update compiler-backed bridge code to read canonical semantic keys plus VS Code projection descriptors from the frontend definition and map them into the baseline transport payload without reinterpreting semantic meaning. File(s): prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/**.

Step 3 - Publish the projection payload through the handshake

What: Make the VS Code client able to receive semantic projection metadata at initialization time. How: Update the protocol mapping layer so the initialize result transports canonical semantic keys and VS Code projection metadata through the agreed experimental surface or another current handshake surface, while keeping semantic theming transport from DEC-0033 intact and coherent. File(s): prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/mapping/**, related server description surfaces.

Step 4 - Lock transport behavior with tests

What: Prevent future drift toward semantic normalization inside LSP. How: Add tests that assert:

1. canonical frontend semantic keys survive transport,
2. VS Code projection entries survive transport,
3. payload structure remains mechanically consumable by the extension,
4. the transport layer does not replace frontend keys with host token categories.

File(s): prometeu-lsp/prometeu-lsp-v1/src/test/java/**, prometeu-lsp/prometeu-lsp-api tests if present.

Test Requirements

Unit Tests

• Validate mapping from frontend projection metadata into baseline transport DTOs.
• Validate transport serialization of canonical keys plus projection entries.

Integration Tests

• Run targeted lsp-v1 tests proving the server handshake exposes both semantic themes and semantic host projection coherently.

Manual Verification

• Inspect the initialize payload and confirm that frontend semantic keys and VS Code projection metadata are both visible.
• Confirm no layer in LSP rewrites canonical semantic keys into a mandatory host taxonomy.

Acceptance Criteria

• LSP transport models carry canonical frontend semantic keys and VS Code projection metadata together.
• The compiler-backed bridge resolves that metadata directly from frontend definitions.
• The initialize payload exposes the metadata mechanically to the extension.
• Tests lock the transport layer against semantic normalization drift.

Dependencies

• DEC-0034 accepted and normatively locked.
• PLN-0072 completes the compiler/frontend projection contract.
• DEC-0033 transport conventions remain in force for visual theme payloads.

Risks

• Reusing visual theme payload structures carelessly could blur the boundary between visual and semantic contracts.
• Flattening transport too aggressively could erase canonical frontend key identity.
• Excessive protocol specialization could make future hosts harder to add.