Intrepid/prometeu-studio

Fork 0

bQUARKz a0e19fd143

editor with write capability

2026-04-04 11:39:04 +01:00

8.6 KiB

Raw Permalink Blame History

Integrated LSP Semantic Read Phase Specification

Status

Active

Applies To

prometeu-studio
prometeu-vfs
prometeu-lsp
the integrated frontend 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 ownership and frontend editing ownership,
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:

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 may be editable under the controlled write wave exposed by prometeu-vfs,
editable supported 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 phase for frontend documents, not an ownership phase for frontend editing.

Rules:

no capability in this phase may override prometeu-vfs access policy, save policy, or snapshot ownership;
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.