# 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 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,
- `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.
- build-facing document ownership remains outside this phase.

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

- save,
- persistence,
- document access policy,
- 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.

## Highlight Ownership Rules

- frontend highlight must come from semantic information provided through `prometeu-lsp`;
- frontend highlight must use frontend-owned color semantics rather than a Studio-local fallback token scheme;
- non-frontend highlight may remain on the existing Studio-local highlighting path in this phase.

## 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

## 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.