108 lines
5.5 KiB
Markdown
108 lines
5.5 KiB
Markdown
---
|
|
id: PLN-0073
|
|
ticket: frontend-semantic-host-projection-flexibility
|
|
title: LSP Semantic Host Projection Transport
|
|
status: done
|
|
created: 2026-05-06
|
|
completed: 2026-05-06
|
|
tags: [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.
|