prometeu-studio/discussion/workflow/plans/PLN-0027-add-frontend-semantic-presentation-contract-and-lsp-descriptor.md

id	ticket	title	status	created	completed	tags
PLN-0027	studio-frontend-owned-semantic-editor-presentation	Add frontend semantic presentation contract to FrontendSpec and expose it through LSP	review	2026-04-02		compiler frontend lsp contract semantic-highlighting

Objective

Implement the frontend-owned semantic presentation contract in FrontendSpec and expose a derived descriptor through LSP without collapsing frontend semantics into host-owned categories.

Background

DEC-0012 requires:

• static contract data in FrontendSpec;
• a simple descriptor containing semanticKeys + resources;
• frontend-owned semantic vocabulary using stable semanticKey values;
• LSP as a hub that derives and exposes the descriptor to Studio;
• no generic semantic-key reduction such as fe-keyword.

Scope

Included

• FrontendSpec contract model additions.
• FE-specific publication of semantic keys and semantic presentation resources.
• Replacement of generic LSP semantic key emission with frontend-owned keys.
• LSP descriptor derivation and API exposure.
• FE-side tests covering contract presence and consistency.

Excluded

• Studio CSS application changes.
• Studio presentation registry migration.
• Removal of legacy Studio stylesheets, except where required to avoid compile/runtime conflicts.

Execution Steps

Step 1 - Extend FrontendSpec with semantic presentation contract

What: Add a static semantic presentation contract to FrontendSpec.

How: Introduce a dedicated descriptor type that carries frontend-owned semanticKeys + resources, wire it into FrontendSpec, and keep FrontendSpec static and frontend-owned.

File(s):

• prometeu-compiler/prometeu-frontend-api/src/main/java/.../FrontendSpec.java
• any adjacent model files needed for the new descriptor type

Step 2 - Publish PBS semantic vocabulary and resources through FrontendSpec

What: Make PBS publish frontend-owned semantic keys and highlight resources.

How: Add a frontend-owned semantic vocabulary model such as PbsSemanticKind -> semanticKey, publish the resulting semantic presentation contract from PBS frontend definitions, and point the descriptor to FE-owned resources.

File(s):

• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSDefinitions.java
• PBS semantic analysis/indexing files that currently assign generic fe-* categories
• FE resource directory under the PBS frontend module

Step 3 - Remove generic semantic key collapse in LSP

What: Stop translating frontend semantics into host-owned generic semantic keys.

How: Replace fe-keyword, fe-type, and similar outputs with frontend-owned semantic keys coming from frontend semantic vocabulary and/or FrontendSpec contract data.

File(s):

• prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/models/SemanticIndex.java
• any LSP DTO/message models that need to surface the descriptor

Step 4 - Expose descriptor from analysis to Studio-facing LSP results

What: Expose a Studio-consumable descriptor derived from the resolved FrontendSpec.

How: Derive the descriptor during analysis/session creation and include it in the LSP surface that Studio consumes for semantic highlight application.

File(s):

• prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspSemanticReadPhase.java
• prometeu-lsp/prometeu-lsp-api/src/main/java/... messages/DTOs
• any semantic session models involved in transport

Step 5 - Add FE contract tests

What: Verify the FE contract is present and coherent.

How: Add frontend tests that fail when semantic presentation contract data is missing, when semantic keys are not published, or when published resources do not match the FE contract shape expectations.

File(s):

• PBS frontend tests under prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/...
• frontend-api tests if FrontendSpec invariants are enforced there

Test Requirements

Unit Tests

• FrontendSpec tests for semantic presentation descriptor presence and shape.
• PBS frontend tests for semantic key publication.
• LSP tests for transport of frontend-owned semantic keys and descriptor data.

Integration Tests

• Analyze a PBS file through LSP and assert that returned semantic highlights use PBS-owned semantic keys.
• Assert that the descriptor surfaced to the consumer contains the expected semanticKeys + resources.

Manual Verification

• Inspect LSP payloads/logs to confirm there is no remaining fe-* semantic key collapse for PBS.

Acceptance Criteria

• FrontendSpec exposes a static semantic presentation contract.
• PBS publishes semantic keys and resources through that contract.
• LSP no longer emits generic host-owned semantic keys for PBS.
• LSP exposes a descriptor derived from resolved FrontendSpec.
• FE tests cover missing contract data and contract consistency.

Dependencies

• Depends on DEC-0012.
• Should land before Studio consumption changes in PLN-0028.

Risks

• Existing semantic indexing code is currently host-owned and may require a larger refactor than expected.
• DTO surface changes can ripple through Studio and tests.
• Resource publication conventions may be inconsistent across future frontends if not modeled cleanly now.