# Integrated LSP Semantic Read Phase Specification

## Status

Active

## Applies To

- `prometeu-studio`
- `prometeu-vfs`
- `prometeu-lsp`
- the frontend read-only semantic phase in the Studio `Code Editor` workspace

## Purpose

Define the normative Studio contract for the integrated frontend semantic-read phase that arrives before any frontend editing release.

This specification stabilizes:

- the phase boundary between semantic read and frontend editing,
- the ownership relationship between `prometeu-vfs`, `prometeu-lsp`, and the Studio editor,
- the minimum semantic capability set for frontend documents,
- the dedicated semantic surface used for structural anchors and guide-aware editor structure,
- the packaging expectations for the public `prometeu-lsp` API surface,
- and the explicit exclusions that remain outside this phase.

## Authority and Precedence

This specification extends:

- [`5. Code Editor Workspace Specification.md`](5.%20Code%20Editor%20Workspace%20Specification.md)
- [`6. Project Document VFS Specification.md`](6.%20Project%20Document%20VFS%20Specification.md)

If this document conflicts with shell-wide Studio rules, shell rules control shell behavior, the Code Editor specification controls workspace-local editor UX, the VFS specification controls document-boundary ownership, and this document controls the integrated semantic-read phase itself.

## Normative Inputs

The integrated semantic-read phase must assume:

- frontend-scoped documents remain hard `read-only`,
- editable non-frontend documents remain governed by the controlled write wave,
- `FrontendSpec.allowedExtensions` remains the source of truth for frontend scope,
- `FrontendSpec` is the canonical source of frontend semantic presentation contract data,
- `prometeu-vfs` owns document state, snapshots, persistence, and access policy,
- and semantic-read over editorial snapshots must remain separate from build-facing ownership.

## Phase Boundary

This phase is a semantic-read phase for frontend documents, not a frontend editing phase.

Rules:

- frontend documents must remain hard `read-only` throughout this phase;
- no capability in this phase may imply frontend save, mutation, or edit-right release;
- the future release of frontend editing requires a separate explicit decision;
- completion, rename, code actions, and formatting remain outside this phase.

## Ownership Rules

- `prometeu-vfs` owns document state, access policy, editorial snapshots, and persistence.
- `prometeu-lsp` is a semantic consumer above `prometeu-vfs`.
- the Studio `Code Editor` owns UX surfaces that render semantic-read output.
- each frontend owns its semantic vocabulary and semantic presentation resources.
- build-facing document ownership remains outside this phase.

`prometeu-lsp` must not become the owner of:

- save,
- persistence,
- document access policy,
- frontend semantic presentation assets,
- or frontend edit-right release.

## Document Source-of-Truth Rules

- opened frontend documents must be analyzed from the in-memory snapshot exposed by `prometeu-vfs`;
- unopened frontend documents may be analyzed from filesystem-backed state exposed through the same `prometeu-vfs` boundary;
- Studio UI code must not bypass `prometeu-vfs` with ad hoc file loading for semantic-read behavior;
- semantic-read over editorial snapshots must not be treated as canonical build input by implication.

## Minimum Capability Set

The minimum semantic capability set of this phase must include:

- diagnostics for frontend documents;
- document symbols for frontend documents;
- workspace symbols for frontend documents;
- outline-facing structural symbol data;
- go-to-definition for frontend documents;
- frontend semantic highlight.

The phase may ship the dedicated structural-anchor surface after the baseline capability set is stable, but Studio and frontend implementations must treat that surface as the canonical source of exact scope-indicator anchoring once it exists.

The phase may also ship a dedicated inline-hint semantic surface.

Once shipped, frontend and Studio implementations must treat that surface as the canonical source of decorative inline hint payloads.

## Highlight Ownership Rules

- frontend highlight must come from semantic information provided through `prometeu-lsp`;
- frontend highlight must use frontend-owned semantic presentation contract data derived from `FrontendSpec`;
- `prometeu-lsp` must expose a dedicated semantic presentation descriptor derived from the resolved `FrontendSpec`;
- that descriptor must remain simple and include frontend-owned `semanticKeys` plus frontend-owned `resources` in the same message surface;
- `prometeu-lsp` must not collapse frontend semantic keys into host-owned generic categories;
- Studio must project semantic keys mechanically to CSS classes without semantic translation;
- frontend semantic presentation resources must remain under frontend `resources/` and be resolved like ordinary Java resources;
- when semantic presentation descriptor data or usable resources are absent, Studio must continue without semantic highlight;
- this condition must not become a product-facing Studio error and may at most produce normal development logs;
- non-frontend highlight may remain on the existing Studio-local highlighting path in this phase.

## Inline Hint Ownership Rules

- frontend inline hints must come from semantic information provided through `prometeu-lsp`;
- frontend hint existence and hint payload semantics remain frontend-owned;
- `prometeu-lsp` must expose a dedicated transport contract for inline hints rather than relying on Studio-local inference;
- `prometeu-lsp` must preserve deterministic anchor information required for host rendering;
- `prometeu-lsp` must not invent host-owned hint policy when a frontend does not publish hints;
- Studio must render transported hints mechanically as host decorations rather than as document text;
- valid inline hint spans must survive partial degradation when the frontend can still produce them;
- invalid or missing hint spans may be omitted locally;
- Studio must not disable all inline hints for a document solely because some hint spans are unavailable.

## Structural Anchor Semantic Surface

Exact structural anchoring for editor scope indicators must not be overloaded into `documentSymbols`.

`documentSymbols` remains the outline and navigation surface.

Guide-oriented structure must be exposed through a dedicated semantic surface for structural anchors and related guide metadata.

That dedicated surface must be frontend-owned and language-agnostic.

The contract must describe generic structural positions rather than PBS-specific brace semantics.

The surface must be able to represent structures whose boundaries are expressed by:

- braces;
- keywords;
- indentation-derived blocks;
- or mixed delimiter schemes.

At minimum, the dedicated structural-anchor surface must be able to communicate:

- structural ranges that can participate in active-scope selection;
- immediate parentage or equivalent information needed to recover the nearest ancestor relationship;
- exact structural anchor positions used for guide start and end placement;
- enough structural identity to distinguish the active structural range from its immediate container.

The semantic-read contract must not require Studio to scan source text in order to discover the final structural anchor positions.

Temporary local heuristics may exist only as development aids. They must not become the canonical production contract.

The exact serialized schema of this dedicated surface may evolve in implementation plans, but any accepted schema must preserve the invariants above.

## Packaging Rules

The public `prometeu-lsp` API should follow flat packaging similar to `prometeu-packer-api`.

Rules:

- public contract surfaces should remain shallow and explicit;
- packages such as `dtos`, `messages`, and `events` are the preferred shape for public API grouping where those surfaces exist;
- deep public packaging by internal implementation concern should be avoided;
- runtime or implementation layering may exist internally, but it must not leak into the public contract surface by default.

## Non-Goals

- frontend editing
- frontend save policy
- completion
- rename
- code actions
- formatting
- build participation inferred from editorial snapshots
- external-editor compatibility requirements
- Studio-owned semantic hint generation

## Exit Criteria

This specification is complete enough when:

- the semantic-read versus frontend-editing phase boundary is explicit,
- `prometeu-vfs` and `prometeu-lsp` ownership remains unambiguous,
- the minimum semantic capability set is explicit,
- frontend and non-frontend highlight ownership is clearly separated,
- and the excluded editing and completion capabilities remain unambiguous.