editor scope guides

This commit is contained in:
2026-04-03 09:52:04 +01:00
parent 18b1967e6d
commit e06be29f4b
10 changed files with 700 additions and 455 deletions
@@ -1,113 +0,0 @@
---
id: AGD-0016
ticket: pbs-service-facade-reserved-metadata
title: SDK Service Bodies Calling Builtin/Intrinsic Proxies as Ordinary PBS Code
status: accepted
created: 2026-04-03
resolved: 2026-04-03
decision: DEC-0013
tags: [compiler, pbs, sdk, stdlib, lowering, service, intrinsic, sdk-interface]
---
## Pain
Domain owner: `compiler/pbs`
The PBS SDK currently supports two stable execution models:
1. public service wrappers over reserved host declarations such as `@sdk:log`, `@sdk:gfx`, and `@sdk:asset`;
2. public builtin-const roots that lower directly to intrinsic owners.
The input surface now needs a service-oriented version of the intrinsic-backed case:
- a public `service Input`;
- a private builtin type plus builtin const proxy used only inside the SDK;
- ordinary PBS service bodies that call the private builtin proxy and return values normally.
Today this shape parses and passes frontend semantics, but executable lowering does not treat imported SDK service methods as ordinary executable call targets with real bodies. As a result, user code like `Input.touch()` and `Input.pad().a().pressed()` fails with `E_SEM_EXEC_LOWERING_UNRESOLVED_CALLEE` even though the service body itself is valid PBS code.
## Context
- `@sdk:input` currently wants to hide the builtin root and expose only the public service.
- The lowering path already knows how to:
- resolve host-backed service wrappers;
- resolve builtin-const-rooted intrinsics.
- The intended rule is that SDK service methods should behave as ordinary PBS methods even when their bodies call builtin/intrinsic proxies such as `LowInput`.
- Existing tests in the PBS frontend assume `Input` chains resolve to intrinsic callsites and to builtin-owned chained receivers.
- The user clarified the desired behavior:
- `declare service Input { fn touch() -> InputTouch { let touch = LowInput.touch(); return touch; } }` must compile as normal PBS service code;
- the body may include locals and additional processing before returning;
- the public callsite does not need to lower directly to the intrinsic as long as the overall executable model works correctly.
- Repository workflow requires decision before plan/implementation. This agenda exists to converge on the normative model first.
## Open Questions
- [x] What executable artifact model should represent SDK service methods so imported user callsites can lower them as ordinary callable bodies rather than as metadata-only surfaces?
Answer: eligible SDK service methods should be represented as ordinary executable callables with lowered bodies available to imported callsites.
- [x] Should `SDK_INTERFACE` continue forbidding emitted executable bodies globally, or should it gain a selective path for executable service methods that are safe to import and call?
Answer: keep the global prohibition by default, but add a narrow selective path for eligible executable SDK service methods.
- [x] How should chained owner propagation work for values returned from SDK service methods whose bodies call builtin intrinsics, such as `Input.touch()` returning `InputTouch` and `Input.pad()` returning `InputPad`?
Answer: owner propagation should follow the value actually returned by the lowered intrinsic call inside the SDK service body, so callers preserve the same chained builtin semantics as direct intrinsic use.
- [x] What constraints must apply so the compiler can support ordinary SDK service bodies without accidentally turning all interface code into full executable implementation code?
Answer: restrict the feature to reserved SDK service methods that stay within a supported executable subset and are explicitly validated as importable/lowerable.
- [x] Which existing frontend tests must be reoriented from "public callsite resolves directly as intrinsic" to "public service callsite compiles normally and intrinsic resolution succeeds inside the imported method body"?
Answer: the `@sdk:input` frontend and lowering tests should be reoriented to validate ordinary service calls, intrinsic lowering inside imported SDK method bodies, and chained owner preservation on returned values.
- [x] What diagnostics should the compiler emit when an SDK service body calls reserved proxies in ways that cannot be imported or lowered safely?
Answer: add dedicated diagnostics for non-importable or non-lowerable executable SDK service bodies instead of collapsing to generic unresolved-callee failures.
## Options
### Option A - Treat SDK Service Bodies as Ordinary Executable Callables
- **Approach:** Preserve executable bodies for eligible SDK service methods and import them as ordinary callable targets. Lowering of user code emits `CALL_FUNC` to the service method, and the service body itself lowers calls like `LowInput.touch()` to intrinsics.
- **Pro:** Matches the intended product model exactly. Keeps service semantics ordinary and avoids facade-specific lowering rules.
- **Con:** Requires widening the current `SDK_INTERFACE` lowering model, which today suppresses emitted function bodies.
- **Maintainability:** Strong if the eligibility rules stay explicit and narrow.
### Option B - Explicit Reserved Facade Metadata on Service Methods
- **Approach:** Add explicit reserved metadata on service methods declaring which intrinsic owner and method they represent. Lowering may continue to skip executable imported service bodies and instead lower the public callsite through the reserved metadata bridge.
- **Pro:** Smaller execution-model change than importing executable service bodies.
- **Con:** It does not deliver the user-requested semantics of "ordinary PBS service code with arbitrary local processing". It also creates a special case distinct from normal service behavior.
- **Maintainability:** Medium. More explicit than inference, but still introduces a second-class meaning for service methods.
### Option C - Keep Builtin Root Public for Intrinsic-Backed SDK Modules
- **Approach:** Continue exposing builtin const roots publicly and avoid service wrappers for intrinsic-backed modules such as `@sdk:input`.
- **Pro:** Reuses the current lowering path with minimal compiler work.
- **Con:** Conflicts directly with the intended SDK API shape and the user requirement that `Input` remain a normal public service.
- **Maintainability:** Medium for the compiler, weak for the SDK/API design because it leaks implementation-facing reserved roots into public user code.
## Discussion
The user clarified that the target model is not a special "facade intrinsic" abstraction. The target model is ordinary service execution:
- SDK service methods should behave like normal PBS service methods;
- they may call private reserved proxies such as `LowInput`;
- they may allocate locals, perform intermediate work, and then return;
- callers should not need direct access to the reserved proxy.
The core mismatch is therefore different from the original framing. `Log`, `Gfx`, and `Assets` work because the compiler already supports the relevant host-backed wrappers under the current SDK model. `Input` fails because intrinsic-backed SDK service bodies are not currently imported and lowered as ordinary executable code paths.
The compiler therefore likely needs first-class support for executable SDK service bodies, or an explicitly accepted alternative that is intentionally less general than normal service semantics.
## Resolution
Recommended direction: pursue **Option A - Treat SDK Service Bodies as Ordinary Executable Callables**.
Why:
- it matches the clarified requirement exactly: the public `service Input` should work as ordinary PBS code;
- it allows locals and additional processing inside the method body without requiring special facade inference;
- it keeps the private builtin proxy as an implementation detail rather than a user-facing surface;
- it avoids introducing a second semantic class of service methods that only pretend to be ordinary services.
Suggested next step:
1. write a decision that defines the SDK executable model for service methods that call reserved proxies;
2. specify how imported SDK service bodies are represented, lowered, and validated;
3. derive an implementation plan from that accepted decision.
The discussion is now converged enough to move to the decision stage.
@@ -0,0 +1,123 @@
---
id: AGD-0017
ticket: studio-editor-scope-guides-and-brace-anchoring
title: Scope guides do Code Editor com active container, active scope e ancoragem estrutural
status: accepted
created: 2026-04-03
resolved: 2026-04-03
decision:
tags:
- studio
- editor
- scope-guides
- braces
- semantic-read
- frontend-contract
---
## Pain
Os scope guides do Code Editor hoje comunicam hierarquia de escopo, mas ainda falham em dois pontos visuais importantes:
- o guide nao comeca no `{` real do bloco; ele nasce aproximadamente no meio da linha inicial do simbolo;
- o editor nao destaca o escopo em que o cursor esta, entao o usuario nao recebe feedback imediato de qual bloco esta ativo.
Isso deixa a feature util, mas incompleta. Em blocos aninhados, a leitura espacial do editor perde precisao justamente no momento em que o guide deveria ajudar mais.
## Context
Domain owner: `studio`
Owner surfaces: `docs/specs/studio/5. Code Editor Workspace Specification.md`, `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
Cross-domain input: frontends que produzem `documentSymbols()` para o Studio
Superficies relevantes hoje:
- `EditorWorkspace` monta os guides a partir de `analysis.documentSymbols()` e repassa o modelo para a paragraph graphic factory em `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`;
- `EditorDocumentScopeGuideModel` projeta guias por linha com `depth` e `GuideSegmentKind`, mas nao carrega coluna nem offset estrutural do brace em `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideModel.java`;
- `EditorDocumentScopeGuideGraphicFactory` desenha `START` e `END` a partir do centro vertical da linha, nao de um token estrutural real, em `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideGraphicFactory.java`;
- os testes atuais do modelo validam apenas shape por linha, nao ancoragem precisa de brace nem estado ativo por cursor, em `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorDocumentScopeGuideModelTest.java`.
Hoje o schema semantico exposto ao Studio entrega `documentSymbols` com `LspRangeDTO(startOffset, endOffset)`, o que e suficiente para inferir linhas de escopo, mas nao suficiente para afirmar onde o `{` de abertura e o `}` de fechamento realmente estao quando:
- o brace esta em outra coluna da mesma linha;
- o header do simbolo se estende por mais de uma linha;
- a linguagem tem formas de bloco em que o range do simbolo nao coincide com o token estrutural que queremos destacar.
## Open Questions
- [x] O escopo ativo deve ser definido sempre como o menor range estrutural que contem o caret, ou existem casos em que o Studio deve promover o parent em vez do bloco mais interno?
Fechado: `active scope` deve ser sempre o menor range estrutural que contem o caret.
- [x] Como o Studio escolhe o `active container` quando o caret esta em blocos aninhados: funcao owner, tipo owner, ou simplesmente o menor ancestor acima do `active scope`?
Fechado: `active container` deve ser o ancestor estrutural imediato acima do `active scope`, sem excecoes semanticas especiais para funcao, tipo ou outro owner.
- [x] O guide deve ancorar no token estrutural real (`{`/`}`), ou basta uma heuristica local no editor que encontre o primeiro brace plausivel dentro do range do simbolo?
Fechado: a ancoragem exata nao deve depender de heuristica textual local como contrato final; o objetivo correto e um anchor estrutural real.
- [x] O contrato correto para essa precisao estrutural pertence ao frontend/LSP semantic read, ou o Studio deve derivar isso localmente a partir do texto do documento?
Fechado: a precisao estrutural pertence ao frontend e deve ser exposta ao Studio como metadata semanticamente owned pelo produtor da linguagem.
- [x] Como tratar linguagens que nao usam braces ou usam formas mistas de delimitacao, sem acoplar o Studio a PBS?
Fechado: o contrato deve falar em `structural anchors` genericos, nao em braces como primitivo normativo.
- [x] O schema atual de `documentSymbols` deve ser enriquecido, ou devemos introduzir uma surface estrutural paralela dedicada a guides/brackets?
Fechado: devemos introduzir uma surface semantica propria para guides/anchors em vez de inflar `documentSymbols`.
## Options
### Option A - Heuristica local no Studio sobre os ranges atuais
- **Approach:** Manter o contrato atual de `documentSymbols` e fazer o Studio procurar braces plausiveis dentro do texto/range de cada simbolo, alem de calcular o escopo ativo localmente pelo caret.
- **Pro:** Menor custo inicial e pouca mudanca de contrato entre frontend e Studio.
- **Con:** A heuristica tende a ser fragil para headers multiline, linguagens sem braces, ranges amplos demais e futuras linguagens com sintaxe diferente de PBS.
- **Maintainability:** Media para baixa. Resolve rapido, mas cristaliza logica estrutural no host visual em vez de no owner da linguagem.
### Option B - Metadata estrutural explicita fornecida pelo frontend
- **Approach:** Enriquecer o payload semantico consumido pelo Studio com posicoes estruturais explicitas para abertura/fechamento de blocos, ou com uma surface propria para scope/bracket guides; o editor usa esse contrato para ancoragem exata e para determinar o escopo ativo.
- **Pro:** Fecha ownership correto no frontend, preserva neutralidade do Studio em relacao a sintaxe e permite ancoragem precisa sem heuristica textual fraca.
- **Con:** Exige mudar o contrato entre semantic read e Studio, propagar implementacao para o frontend e decidir um schema que nao fique PBS-especifico.
- **Maintainability:** Forte. A precisao estrutural fica no produtor semantico, onde o parse e o conhecimento de linguagem ja existem.
### Option C - Abordagem hibrida em duas waves
- **Approach:** Implementar primeiro um gutter minimalista com no maximo duas linhas visiveis: `active container` e `active scope`, ambos calculados localmente a partir dos ranges atuais; tratar a ancoragem exata no `{` como uma extensao posterior baseada em metadata estrutural explicita.
- **Pro:** Entrega contexto e foco ao mesmo tempo, com pouco ruido, sem bloquear na extensao de contrato e sem puxar o Studio para heuristica sintatica como solucao final.
- **Con:** Exige definir semanticamente o que conta como `active container` e pode exigir retrabalho pequeno no modelo do editor quando a metadata estrutural chegar.
- **Maintainability:** Boa, se a primeira wave permanecer estritamente limitada a duas linhas sem ancestry aberta.
## Discussion
Os dois sintomas nao tem o mesmo peso arquitetural.
Destacar o escopo ativo parece um problema majoritariamente local do editor, especialmente se a primeira wave for minimalista e restrita ao gutter:
- o `CodeArea` ja conhece caret/paragrafo atual;
- o modelo atual ja conhece os ranges de escopo por linha;
- em primeira aproximacao, o editor consegue descobrir qual range contem o cursor sem precisar saber a coluna exata do `{`;
- renderizar no maximo duas linhas (`active container` e `active scope`) preserva contexto sem voltar ao mapa completo de ancestry.
Ja a ancoragem precisa do guide no brace parece um problema de contrato estrutural:
- o modelo atual nao sabe onde o brace real esta;
- usar apenas `startOffset/endOffset` do simbolo empurra heuristica sintatica para dentro do Studio;
- isso fica especialmente fraco num editor que ja foi desenhado para ser multi-frontend.
Por isso, vale separar claramente:
1. `active container` e `active scope` como comportamento visual local, minimalista, restrito ao gutter e derivado dos ranges atuais;
2. `brace anchoring` como capacidade estrutural que talvez exija metadata adicional do frontend.
O risco de tentar resolver tudo localmente no Studio e transformar o host visual em pseudo-parser por linguagem.
O risco oposto e bloquear uma melhoria visual simples do cursor enquanto esperamos um contrato estrutural maior ficar pronto.
## Resolution
Recommended direction: seguir com **Option C**.
A agenda deve convergir para uma decisao com os seguintes fechamentos:
1. a primeira wave deve manter o scope indicator no gutter, de forma minimalista e sem poluicao visual;
2. a primeira wave pode renderizar no maximo duas linhas no gutter: `active container` e `active scope`, sem ancestry arbitraria e sem mapa completo de guides;
3. `active scope` deve ser o menor range estrutural que contem o caret;
4. `active container` deve ser o ancestor estrutural imediato acima do `active scope`;
5. o destaque desses estados pelo cursor deve ser tratado como capacidade local do editor, usando os ranges semanticos ja disponiveis, desde que a regra fique language-agnostic;
6. a apresentacao visual concreta desses indicadores deve continuar frontend-owned; o contrato do Studio nao deve fixar cores, tracos ou estilos especificos como regra normativa;
7. a ancoragem exata do guide nao deve ser resolvida por heuristica textual como contrato final;
8. a precisao estrutural deve ser exposta por metadata frontend-owned;
9. essa metadata deve falar em `structural anchors` genericos, nao em braces como primitivo normativo;
10. guides/anchors devem viver em uma surface semantica propria, em vez de estender `documentSymbols`.
Next step suggestion: converter esta agenda em uma `decision` que feche o boundary entre Studio e frontend para structural scope metadata, diferencie formalmente `active scope` de `brace anchor`, e declare a wave inicial aceitavel para o Code Editor.