---
id: PLN-0076
ticket: pbs-lsp-editor-assistance-wave-1
title: LSP Completion, Hover, and Signature Help over Editorial Resolution
status: open
created: 2026-05-08
completed:
tags: [studio, lsp, protocol, completion, hover, signature-help, editor]
---

## Objective

Expose `completion`, real `hover`, and `signature help` through the project-scoped LSP stack by projecting the compiler-backed editorial resolution surface into explicit protocol capabilities and request handlers.

## Background

`DEC-0035` requires `studio/lsp` to be the operational owner of these editor features while remaining faithful to compiler-backed symbol, member, and signature resolution. The current LSP path only handles diagnostics, semantic tokens, and a placeholder hover.

## Scope

### Included

- Extend the internal bridge/API with completion and signature-help operations.
- Replace placeholder hover with symbol-resolved hover.
- Announce LSP capabilities for completion and signature help.
- Add message models/mappers/tests for the new request/response paths.

### Excluded

- Creation of the underlying compiler editorial model itself.
- Authored documentation syntax.
- VS Code-specific UI behavior beyond normal LSP consumption.

## Non-Goals

- `go to definition`, `references`, `rename`, formatter, code actions, or quick fixes.
- Rich workspace-wide indexing beyond what the shared editorial surface already provides.

## Execution Steps

### Step 1 - Extend the LSP bridge contract

**What:** Add compiler-backed editor-assistance operations to the bridge.
**How:** Evolve `LanguageServiceBridge` and related internal messages to support at minimum:

1. completion requests;
2. symbol-resolved hover payloads;
3. signature-help requests.

The bridge contract must align structurally with the shared editorial resolution surface rather than inventing a second feature-specific abstraction.
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/**`, `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/**`.

### Step 2 - Implement compiler-backed request handling

**What:** Wire LSP requests to compiler-backed editorial resolution.
**How:** Update `CompilerLanguageServiceBridge` so it:

1. resolves completion candidates from local/import/member contexts;
2. resolves hover payloads from symbol identity, origin, and signatures;
3. resolves active call signatures for `signature help`.

This step must remove the current fixed hover placeholder.
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/**`.

### Step 3 - Announce and map protocol capabilities

**What:** Make the server advertise the new feature set and map payloads into lsp4j types.
**How:** Update protocol mappers and text-document service so the server announces:

1. `completionProvider`;
2. `signatureHelpProvider`;
3. improved `hoverProvider` backed by real payloads.

Map completion items, hover markdown, and signature-help structures into concrete LSP responses.
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/**`, `.../mapping/**`.

### Step 4 - Add transport and conformance tests

**What:** Prevent regression to placeholder/editor-local behavior.
**How:** Add tests that verify:

1. capabilities are announced correctly;
2. completion returns compiler-backed candidates;
3. hover no longer returns the baseline placeholder;
4. signature-help returns deterministic active-signature information.

**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/test/java/**`.

## Test Requirements

### Unit Tests

- DTO/model invariants for completion, hover, and signature-help payloads.
- Mapper tests for lsp4j conversion.

### Integration Tests

- LSP request/response tests using realistic PBS snippets with locals, imports, and member access.

### Manual Verification

- Connect the VS Code extension and confirm server capabilities include completion and signature help.
- Confirm hover content changes with the hovered symbol rather than returning static baseline text.

## Acceptance Criteria

- [ ] The LSP bridge exposes completion and signature-help operations in addition to diagnostics, hover, and semantic tokens.
- [ ] Hover is symbol-resolved and no longer hardcoded placeholder text.
- [ ] The server advertises completion and signature-help capabilities.
- [ ] Completion, hover, and signature help all derive from the same compiler-backed editorial surface.

## Dependencies

- `DEC-0035` accepted and normatively locked.
- `PLN-0075` for the shared compiler-backed editorial resolution surface.

## Risks

- Protocol mapping can drift from compiler payload shape if feature-specific shortcuts are added.
- Active parameter/signature calculation may be brittle around incomplete syntax unless request handling is conservative.
- Completion can feel noisy if candidate ranking or filtering is too weak in wave 1.