implements PLN-0033 inline hint spec and contract propagation

discussion/index.ndjson

@@ -15,4 +15,4 @@
 {"type":"discussion","id":"DSC-0014","status":"done","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
 {"type":"discussion","id":"DSC-0015","status":"done","ticket":"pbs-service-facade-reserved-metadata","title":"SDK Service Bodies Calling Builtin/Intrinsic Proxies as Ordinary PBS Code","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["compiler","pbs","sdk","stdlib","lowering","service","intrinsic","sdk-interface"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"discussion/lessons/DSC-0015-pbs-service-facade-reserved-metadata/LSN-0030-sdk-service-bodies-over-private-reserved-proxies.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}]}
 {"type":"discussion","id":"DSC-0016","status":"open","ticket":"studio-editor-scope-guides-and-brace-anchoring","title":"Scope Guides do Code Editor com ancoragem exata em braces e destaque do escopo ativo","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","scope-guides","braces","semantic-read","frontend-contract"],"agendas":[{"id":"AGD-0017","file":"AGD-0017-studio-editor-scope-guides-and-brace-anchoring.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0014","file":"DEC-0014-studio-editor-active-scope-and-structural-anchors.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"plans":[{"id":"PLN-0030","file":"PLN-0030-studio-active-container-and-active-scope-gutter-wave-1.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0031","file":"PLN-0031-studio-structural-anchor-semantic-surface-specification.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0032","file":"PLN-0032-frontend-structural-anchor-payloads-and-anchor-aware-tests.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}],"lessons":[]}
-{"type":"discussion","id":"DSC-0017","status":"open","ticket":"studio-editor-inline-type-hints-for-let-bindings","title":"Inline Type Hints for Let Bindings in the Studio Editor","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","inline-hints","inlay-hints","lsp","pbs","type-inference"],"agendas":[{"id":"AGD-0018","file":"AGD-0018-studio-editor-inline-type-hints-for-let-bindings.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0015","file":"DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03","ref_agenda":"AGD-0018"}],"plans":[{"id":"PLN-0033","file":"PLN-0033-inline-hint-spec-and-contract-propagation.md","status":"open","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0034","file":"PLN-0034-lsp-inline-hint-transport-contract.md","status":"open","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0035","file":"PLN-0035-pbs-inline-type-hint-payload-production.md","status":"open","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0036","file":"PLN-0036-studio-inline-hint-rendering-and-rollout.md","status":"open","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]}],"lessons":[]}
+{"type":"discussion","id":"DSC-0017","status":"open","ticket":"studio-editor-inline-type-hints-for-let-bindings","title":"Inline Type Hints for Let Bindings in the Studio Editor","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","inline-hints","inlay-hints","lsp","pbs","type-inference"],"agendas":[{"id":"AGD-0018","file":"AGD-0018-studio-editor-inline-type-hints-for-let-bindings.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0015","file":"DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03","ref_agenda":"AGD-0018"}],"plans":[{"id":"PLN-0033","file":"PLN-0033-inline-hint-spec-and-contract-propagation.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0034","file":"PLN-0034-lsp-inline-hint-transport-contract.md","status":"open","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0035","file":"PLN-0035-pbs-inline-type-hint-payload-production.md","status":"open","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0036","file":"PLN-0036-studio-inline-hint-rendering-and-rollout.md","status":"open","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]}],"lessons":[]}

discussion/workflow/plans/PLN-0033-inline-hint-spec-and-contract-propagation.md

@@ -0,0 +1,103 @@
+---
+id: PLN-0033
+ticket: studio-editor-inline-type-hints-for-let-bindings
+title: Inline hint specification and contract propagation
+status: done
+created: 2026-04-03
+completed: 2026-04-03
+tags: [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
+
+- [x] Studio editor specs define inline hints as decorative, host-generic, and final-state inline real.
+- [x] Semantic-read specs define frontend-owned hint transport and partial-degradation preservation.
+- [x] Compiler/frontend contract language preserves frontend ownership of hint semantics.
+- [x] 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.

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

@@ -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:

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

@@ -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
 

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

@@ -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