Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/discussion/workflow/plans/PLN-0033-inline-hint-spec-and-contract-propagation.md

4.6 KiB
Raw Blame History

id ticket title status created completed tags
PLN-0033 studio-editor-inline-type-hints-for-let-bindings Inline hint specification and contract propagation done 2026-04-03 2026-04-03
studio
editor
specs
inline-hints
lsp
frontend-contract

Objective

Propagate DEC-0015 into the normative specification surfaces that define editor responsibilities, LSP semantic-read transport, and compiler/frontend contract authority for inline hints.

Background

DEC-0015 locks inline hints as a host-generic editor capability with frontend-defined payloads, LSP-enforced transport, Studio rendering, decorative-only interaction, and partial-degradation preservation. No implementation plan may weaken those rules by inference.

The repository already has normative surfaces for editor behavior, semantic-read transport, and frontend-owned semantic contracts. Those surfaces must be updated before implementation splits across LSP, PBS, and Studio code.

Scope

Included

  • Propagate DEC-0015 to Studio editor specs.
  • Propagate DEC-0015 to integrated semantic-read specs.
  • Extend compiler/frontend contract language where needed so frontend-owned hint metadata has a stable authority surface.
  • Define the normative distinction between transitional approximation and final inline rendering.

Excluded

  • LSP DTO implementation.
  • PBS hint payload production.
  • Studio rendering code.

Execution Steps

Step 1 - Update the Code Editor workspace specification for inline hint rendering

What: Add normative editor requirements for decorative inline hints, host responsibilities, and inline-real final rendering.

How: Update the Studio Code Editor specification to state that:

  • inline hints are host-generic editor capabilities;
  • hint content remains frontend-owned;
  • the editor renders but does not invent hints;
  • hints are decorative only and do not alter text, selection, caret movement, or persistence;
  • a transitional approximate stage may exist only as an explicit rollout step;
  • the final completed capability is real inline rendering.

File(s):

  • docs/specs/studio/5. Code Editor Workspace Specification.md

Step 2 - Update the semantic-read phase specification for inline hint transport

What: Define inline hint transport as part of the semantic-read contract.

How: Update the semantic-read specification so it normatively states:

  • inline/inlay hints are frontend-owned semantic payloads transported through prometeu-lsp;
  • LSP owns the DTO and transport contract but not hint semantics;
  • valid hint spans must survive partial degradation;
  • the transport must preserve deterministic anchor information needed by Studio rendering.

File(s):

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

Step 3 - Update compiler/frontend contract authority for frontend-owned hint metadata

What: Extend the compiler/frontend contract language so frontend-owned editor hint metadata has an explicit authority surface parallel to semantic presentation.

How: Update the compiler entrypoint/frontend contract specification to state that FrontendSpec or an equivalent accepted frontend-owned semantic contract surface remains the canonical source for static hint contract metadata when such metadata is required by downstream consumers.

The text must not imply Studio-owned or LSP-owned semantic hint policy.

File(s):

  • docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md

Test Requirements

Unit Tests

  • Not applicable for this spec-only plan.

Integration Tests

  • Not applicable for this spec-only plan.

Manual Verification

  • Review the updated specs against DEC-0015 and confirm all normative points are represented.
  • Confirm the final-state requirement still says inline real rendering.
  • Confirm the specs do not give Studio authority over hint existence or content.

Acceptance Criteria

  • Studio editor specs define inline hints as decorative, host-generic, and final-state inline real.
  • Semantic-read specs define frontend-owned hint transport and partial-degradation preservation.
  • Compiler/frontend contract language preserves frontend ownership of hint semantics.
  • The specification set is sufficient for code plans without reopening DEC-0015.

Dependencies

  • Accepted decision DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md
  • Existing Studio and compiler specifications.

Risks

  • Under-specifying the contract may force DTO churn later.
  • Overloading existing semantic presentation wording may blur the distinction between static presentation metadata and dynamic hint payload transport.