prometeu-studio/discussion/workflow/plans/PLN-0067-compiler-backed-dumb-lsp-server-baseline.md

id	ticket	title	status	created	completed	tags
PLN-0067	studio-new-lsp-api-and-v1-boundary	Compiler-Backed Dumb LSP Server Baseline	open	2026-05-05		studio lsp compiler baseline protocol vscode

Objective

Establish a maintainable, compiler-backed baseline inside lsp-v1 that keeps the server behavior deliberately simple while creating the seams required for later semantic layering.

Background

DEC-0032 explicitly allows wave 1 to remain semantically thin, but it forbids keeping an ad hoc mock structure as the long-term coding pattern. The backend therefore needs a baseline that is:

• dumb in behavior when necessary,
• but already correctly composed over compiler services,
• and already structured for layered enrichment later.

Scope

Included

• Create compiler-facing service seams used by lsp-v1.
• Provide a small, explicit set of LSP capabilities or responses that prove the adapter shape.
• Keep the VS Code extension compatible with the current TCP model.
• Document the temporary behavioral limits in code and tests.

Excluded

• Full diagnostics, definition, symbols, inlay hints, or multi-file semantic completeness.
• Automation channel work.
• Non-TCP transport experiments.

Non-Goals

• Matching the full final language feature set.
• Recreating the deleted legacy prometeu-lsp behavior.
• Optimizing for performance before the baseline structure is validated.

Execution Steps

Step 1 - Define compiler-facing bridge services inside lsp-v1

What: Introduce explicit bridge classes or adapters between protocol handlers and compiler. How: Create narrow services inside lsp-v1 that own calls into compiler entrypoints. Even if the first concrete responses are stubbed or partial, the protocol handlers must already call through these seams instead of embedding compiler knowledge everywhere. File(s): prometeu-lsp/prometeu-lsp-v1/src/main/java/**, relevant prometeu-compiler integration points when discoverable.

Step 2 - Implement a minimal but structured capability slice

What: Keep the server intentionally dumb, but no longer structurally improvised. How: Choose a small capability surface such as initialize, shutdown, and one lightweight language feature or health response. The exact feature set may stay narrow, but the code must already follow the final layering:

• protocol request handling,
• bridge service invocation,
• result mapping.

File(s): prometeu-lsp/prometeu-lsp-v1/src/main/java/**, potentially tools/vscode-extension/src/extension.ts if initialization expectations need tightening.

Step 3 - Codify temporary behavior limits

What: Make the current limitations explicit instead of implicit. How: Add tests and lightweight documentation/comments that define the intentionally supported baseline behavior so future work can add capability in layers without guessing what the "mock" currently means. File(s): prometeu-lsp/prometeu-lsp-v1/src/test/java/**, targeted source comments where they reduce ambiguity.

Test Requirements

Unit Tests

• Verify protocol handlers call the correct bridge services.
• Verify compiler bridge services can be instantiated and return stable baseline results.
• Verify no handler bypasses the bridge layer to embed semantic logic ad hoc.

Integration Tests

• Run a targeted Studio/LSP integration proving the VS Code client can initialize against the dumb server.
• Run compiler-related tests needed to validate the consumed service seams.

Manual Verification

• Connect from VS Code and confirm the server initializes and remains stable.
• Confirm the limited capability set behaves predictably and does not masquerade as richer support than actually implemented.

Acceptance Criteria

• lsp-v1 talks to compiler through explicit bridge services.
• The baseline server behavior remains intentionally simple but structurally clean.
• At least one minimal end-to-end capability slice proves the final layering.
• The extension can still connect over TCP without protocol regressions.
• Temporary semantic limits are explicit in tests and code structure.

Dependencies

• DEC-0032 accepted and normatively locked.
• PLN-0065 for module/boundary setup.
• PLN-0066 for project-scoped lifecycle integration.

Risks

• A "temporary" dumb server can calcify unless the seams are truly explicit and tested.
• Over-stubbing can hide compiler integration issues that should be surfaced early.
• Picking too many baseline features in this wave can dilute the architectural focus.