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

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.

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.

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

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.