diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 4263245e..66b1d112 100644 --- a/discussion/index.ndjson +++ b/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":[]} diff --git a/discussion/workflow/plans/PLN-0033-inline-hint-spec-and-contract-propagation.md b/discussion/workflow/plans/PLN-0033-inline-hint-spec-and-contract-propagation.md new file mode 100644 index 00000000..5b3606a1 --- /dev/null +++ b/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. diff --git a/docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md b/docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md index 580db560..01936e51 100644 --- a/docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md +++ b/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: diff --git a/docs/specs/studio/5. Code Editor Workspace Specification.md b/docs/specs/studio/5. Code Editor Workspace Specification.md index 766b3cfd..45d341c7 100644 --- a/docs/specs/studio/5. Code Editor Workspace Specification.md +++ b/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 diff --git a/docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md b/docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md index 11b9f7bf..ece027db 100644 --- a/docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md +++ b/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