prometeu-studio/docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md

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
• 6. Project Document VFS Specification.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.

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.

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.