implements PLN-0033 inline hint spec and contract propagation

This commit is contained in:
2026-04-03 11:21:28 +01:00
parent e8ec9973cd
commit 08f28b4a7d
5 changed files with 180 additions and 1 deletions
@@ -210,6 +210,25 @@ This contract MUST NOT:
Tooling consumers such as integrated LSP and Studio MAY derive downstream descriptors from `FrontendSpec`, but they MUST treat `FrontendSpec` as the canonical source rather than a host-owned replacement contract.
## 8.2 Frontend-Owned Inline Hint Contract Authority
Frontend-owned inline hint semantics MUST remain frontend-authored even when transported through tooling consumers.
When downstream semantic consumers require static contract metadata for inline hints, that metadata MUST come from `FrontendSpec` or from another accepted frontend-owned contract surface explicitly introduced for that purpose.
At minimum, any accepted frontend-owned inline hint contract authority MUST preserve:
1. frontend ownership of hint existence policy,
2. frontend ownership of hint semantic meaning,
3. enough contract metadata for `prometeu-lsp` to transport hint payloads without inventing host-owned semantics,
4. and enough contract clarity for Studio to render hints mechanically rather than semantically reinterpret them.
This authority model MUST NOT:
1. move semantic inline hint ownership into Studio,
2. move semantic inline hint policy into LSP,
3. or imply that the host editor may synthesize semantic hints when the frontend did not publish them.
## 9. Public Surface Rule
The shared compiler public surface MUST expose explicit entrypoints equivalent in meaning to:
@@ -223,6 +223,45 @@ Rules:
- The workspace must not surface this condition as a product-facing editor error.
- The workspace must not treat semantic-read over editorial snapshots as authorization for frontend save, mutation, or build participation.
## Inline Hint Rules
Inline hints must be treated as a host-generic editor capability rather than as a PBS-only feature.
The Studio `Code Editor` must render inline hints only from frontend-owned semantic payloads transported through the integrated semantic-read phase.
The editor must not invent:
- hint existence policy,
- hint text,
- hint categories,
- or host-owned semantic fallback hints.
If a frontend publishes valid inline hints through the accepted semantic-read contract, the editor must render them.
If a frontend does not publish inline hints for a construct, the editor must not synthesize one.
Inline hints are decorative only.
Therefore the editor must ensure that inline hints:
- do not modify document text;
- do not become part of persisted file content;
- do not participate as copied document text;
- do not redefine selection ranges;
- and do not redefine caret movement over the text model.
The completed capability must render inline hints as real inline editor decorations attached to document positions inside the editor flow.
An approximate visual implementation may exist only as an explicit transitional wave.
Any transitional approximation:
- must be documented as transitional;
- must not redefine the final editor contract;
- and must converge to real inline rendering in a later execution step.
When only some inline hint spans remain valid under degraded semantic analysis, the editor must continue rendering those valid spans rather than disabling all inline hints for the document.
## Scope Indicator Rules
The default semantic scope-indicator surface in the Code Editor must remain the gutter.
@@ -314,6 +353,7 @@ Persisting that state across Studio executions is deferred.
- completion, rename, code actions, or formatting
- a normative editor event contract in this wave
- any implication that editor-owned in-memory snapshots participate in the build
- host-owned semantic inline hint policy
## Exit Criteria
@@ -91,6 +91,10 @@ The minimum semantic capability set of this phase must include:
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`;
@@ -104,6 +108,18 @@ The phase may ship the dedicated structural-anchor surface after the baseline ca
- 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`.
@@ -157,6 +173,7 @@ Rules:
- formatting
- build participation inferred from editorial snapshots
- external-editor compatibility requirements
- Studio-owned semantic hint generation
## Exit Criteria