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,159 +0,0 @@
---
id: DEC-0013
ticket: pbs-service-facade-reserved-metadata
title: Executable SDK Service Bodies for Builtin/Intrinsic-Backed Public Services
status: accepted
created: 2026-04-03
accepted: 2026-04-03
agenda: AGD-0016
plans: [PLN-0029]
tags: [compiler, pbs, sdk, stdlib, lowering, service, intrinsic, sdk-interface]
---
## Decision
Domain owner: `compiler/pbs`
The PBS compiler SHALL support a restricted executable-service model inside `SDK_INTERFACE` sources.
Under this model:
1. public SDK `service` methods MAY contain ordinary PBS executable bodies;
2. those bodies MAY call reserved hosts, reserved builtin const proxies, and reserved intrinsic-backed values;
3. imported user callsites to eligible SDK service methods SHALL lower as ordinary callable invocations of the SDK service method body;
4. intrinsic lowering SHALL occur inside the lowered SDK service body when the body calls the private reserved proxy;
5. public user code MUST NOT be required to import or reference the private reserved proxy directly.
This decision explicitly rejects the requirement that intrinsic-backed public SDK services MUST lower directly from the user callsite to `CALL_INTRINSIC`.
For eligible SDK service methods, the normative lowering model is:
- public user callsite lowers as callable/service method invocation;
- imported SDK service body lowers as executable PBS code;
- reserved proxy calls inside that body lower through the existing intrinsic or host machinery;
- returned values preserve the owner and chaining semantics established by the lowered reserved operation.
`@sdk:input` SHALL be supported by this model. A service body such as:
```pbs
declare service Input {
fn touch() -> InputTouch {
let touch = LowInput.touch();
return touch;
}
}
```
MUST be valid as ordinary SDK service code, provided it remains within the supported restricted subset defined below.
## Rationale
This decision matches the intended SDK API shape:
- public SDK surfaces such as `Input` should be expressed as services when that is the product-facing abstraction;
- private reserved builtins and builtin const proxies should remain implementation details;
- SDK authors must be allowed to write normal service bodies with locals and intermediate processing rather than being forced into synthetic facade metadata or direct public builtin roots.
The alternative of explicit facade metadata on public service methods was rejected because it creates a second semantic class of services that only imitate ordinary PBS code. The alternative of keeping intrinsic roots public was rejected because it leaks reserved implementation surfaces into the user API.
## Technical Specification
### 1. Eligible Surface
The compiler SHALL define an explicit category of eligible executable SDK service methods.
An eligible executable SDK service method:
1. MUST be declared in a `SourceKind.SDK_INTERFACE` module;
2. MUST belong to a `service` declaration;
3. MUST remain within the restricted executable subset defined by compiler validation;
4. MUST be importable as a callable body by user modules.
Non-eligible declarations in `SDK_INTERFACE` MUST continue to follow the existing non-executable interface rules.
### 2. SDK Interface Execution Boundary
`SDK_INTERFACE` SHALL remain non-executable by default.
The compiler SHALL introduce a narrow exception for eligible SDK service methods only. This exception MUST NOT implicitly generalize to arbitrary interface-level functions, globals, or unrestricted executable declarations.
### 3. Import Model
When a user module imports a public SDK service:
1. the imported semantic surface MUST continue to expose the service method signatures;
2. the lowering pipeline MUST also have access to the executable body of each eligible imported SDK service method;
3. a user callsite such as `Input.touch()` MUST be lowerable as an ordinary callable invocation of the imported SDK service method.
The compiler MUST NOT require special public facade metadata to connect the user callsite to the reserved intrinsic owner when the service body already expresses the call explicitly.
### 4. Lowering Model
For an eligible imported SDK service method:
1. the public callsite SHALL lower as a callable invocation;
2. the imported SDK service body SHALL be lowered with the same executable-body discipline applied to ordinary PBS executable code, subject to the restricted subset;
3. calls inside that body to reserved hosts SHALL continue to use host lowering;
4. calls inside that body to reserved builtin const proxies SHALL continue to use intrinsic lowering;
5. any returned reserved value SHALL preserve the return owner and chaining semantics inferred from the lowered reserved call.
As a result:
- `Input.touch()` MAY lower to a callable invocation of the imported SDK method;
- `LowInput.touch()` inside the SDK body SHALL lower to the intrinsic owner `input.touch`;
- chained user code such as `Input.touch().x()` and `Input.pad().a().pressed()` MUST remain valid when the returned owner chain is supported by the reserved metadata.
### 5. Restricted Executable Subset
The compiler SHALL validate eligible executable SDK service methods against an explicit restricted subset.
At minimum, the first supported subset MUST permit:
- local bindings;
- ordinary return statements;
- calls to reserved hosts;
- calls to reserved builtin const proxies and their intrinsic-return values;
- straightforward expression composition needed for wrapper-style service methods.
The first supported subset MUST NOT silently permit unsupported executable constructs. If a construct is outside the supported subset, the compiler MUST emit a dedicated diagnostic.
Whether control flow beyond straightforward wrapper composition is included in the first wave SHALL be decided in planning and implementation, but the compiler MUST validate the boundary explicitly rather than relying on accidental behavior.
### 6. Diagnostics
The compiler SHALL add dedicated diagnostics for executable SDK service bodies that cannot be imported or lowered safely.
These diagnostics MUST distinguish this failure mode from generic unresolved callee failures.
At minimum, diagnostics SHALL cover:
- SDK service bodies that use unsupported executable constructs;
- imported SDK service methods that are not eligible for executable lowering;
- inconsistencies between an imported SDK service signature and the lowered executable body shape;
- reserved proxy use that cannot preserve required return-owner or chaining behavior.
### 7. Tests and Conformance
The compiler test suite SHALL be updated to reflect the new normative model.
Tests MUST cover:
1. public SDK service callsites lowering successfully as callable invocations;
2. intrinsic lowering occurring inside the imported SDK service body;
3. returned reserved owners preserving chained method access for values such as `InputTouch` and `InputPad`;
4. use of locals and intermediate processing inside SDK service bodies;
5. dedicated diagnostics for unsupported executable SDK service bodies.
Existing tests that assume the public `Input` callsite itself MUST resolve directly to an intrinsic SHALL be revised to match this decision.
## Constraints
- This decision applies to `compiler/pbs` and to SDK surfaces loaded through `SDK_INTERFACE`.
- This decision does not authorize arbitrary executable code throughout interface modules.
- This decision does not require public exposure of private reserved builtin roots.
- This decision does not replace the existing host-backed SDK service model; it extends the compiler so intrinsic-backed SDK services can use ordinary service bodies.
- Any future extension of the restricted executable subset MUST be treated as a follow-up decision or explicit revision if it changes the initial boundary materially.
## Revision Log
- 2026-04-03: Initial draft from AGD-0016.
@@ -0,0 +1,147 @@
---
id: DEC-0014
ticket: studio-editor-scope-guides-and-brace-anchoring
title: Code Editor active container, active scope, and frontend-owned structural anchors
status: accepted
created: 2026-04-03
accepted: 2026-04-03
agenda: AGD-0017
plans:
- PLN-0030
- PLN-0031
- PLN-0032
tags:
- studio
- editor
- scope-guides
- semantic-read
- frontend-contract
- structural-anchors
---
## Decision
The Studio Code Editor SHALL keep scope indicators in the gutter.
The initial wave SHALL render at most two simultaneous structural indicators:
1. `active container`
2. `active scope`
The Studio MUST NOT render the full ancestry map or the current multi-guide stack as the default active-scope presentation.
`active scope` SHALL be defined as the smallest structural range that contains the caret.
`active container` SHALL be defined as the immediate structural ancestor of `active scope`.
The Studio SHALL determine `active container` and `active scope` locally from semantic ranges already available to the editor, provided that the rule remains language-agnostic.
The concrete visual presentation of these two indicators SHALL remain frontend-owned. The Studio contract MUST NOT normatively fix colors, stroke style, dashed versus solid rendering, or equivalent stylistic choices.
Exact guide anchoring MUST NOT rely on local textual heuristics as the final contract. Exact anchoring SHALL be backed by frontend-owned structural metadata.
That structural metadata SHALL be expressed as generic `structural anchors`, not as PBS-specific brace semantics. The contract MUST remain language-agnostic and applicable to languages that do not use `{` / `}` as primary delimiters.
Structural anchors and guide-specific structural data SHALL live in a dedicated semantic surface. They MUST NOT be folded into `documentSymbols` as an overloaded extension of the outline/navigation payload.
## Rationale
The current gutter guides already prove that structural ranges are useful, but the existing presentation is too noisy and not precise enough:
- multiple simultaneous guide columns create visual pollution;
- the current guide start/end positions are derived from symbol line ranges, not from exact structural anchors;
- the current model is good enough to identify containing ranges, but not good enough to express precise opening/closing structure.
The accepted direction separates two concerns that have different architectural weights:
- `active container` and `active scope` are local editor-state projections and can be derived from existing semantic ranges;
- exact structural anchoring is a language-owned concern and belongs in frontend metadata rather than Studio-local syntax heuristics.
Restricting the default visualization to at most two indicators preserves context without reviving the clutter of a full ancestry map.
Keeping visual styling frontend-owned preserves the existing design direction in which semantic presentation belongs to the frontend rather than to Studio-global hardcoded rendering rules.
## Technical Specification
### 1. Gutter Indicator Model
The editor gutter SHALL support exactly two semantic slots for active structural indication:
- `activeContainer`
- `activeScope`
The first implementation wave MAY omit `activeContainer` when no valid ancestor exists. It MUST NOT synthesize a non-existent container.
The editor MUST compute `activeScope` by selecting the smallest structural range that contains the caret offset.
The editor MUST compute `activeContainer` by selecting the immediate parent structural range of `activeScope`.
The editor MUST NOT promote a higher semantic owner such as function, type, or module when a nearer structural ancestor exists.
### 2. Presentation Ownership
The editor SHALL expose enough state for the presentation layer to distinguish:
- container indicator
- scope indicator
The decision intentionally leaves the following presentation properties non-normative:
- color
- opacity
- stroke thickness
- dashed versus solid treatment
- cap styling
- equivalent visual emphasis rules
Those choices SHALL remain frontend-owned or presentation-owned.
### 3. Structural Anchoring
Exact anchor positions for guide start/end SHALL come from semantic structural metadata produced by the language/frontend side.
Studio MUST treat those anchors as generic structural positions rather than brace-specific tokens.
The metadata model MUST support languages where structural delimiters are:
- braces
- keywords
- indentation-derived constructs
- mixed delimiter schemes
### 4. Semantic Surface Boundary
`documentSymbols` SHALL remain the outline/navigation surface.
Structural guide metadata SHALL be introduced as a distinct semantic surface dedicated to:
- structural ranges
- structural parent/child relationships when needed
- structural anchors used by guide rendering
Studio MUST NOT infer the final structural contract by scanning source text for likely braces inside symbol ranges.
Local heuristics MAY exist only as temporary debugging aids during development. They MUST NOT become the canonical production contract.
### 5. Propagation Targets
This decision SHALL propagate to:
- Studio editor implementation in `prometeu-studio`
- Studio-facing semantic read contracts in `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
- Code Editor presentation and interaction behavior in `docs/specs/studio/5. Code Editor Workspace Specification.md`
- frontend-produced semantic payloads that eventually expose structural anchors
- tests covering active scope selection, active container selection, and anchor-aware rendering
## Constraints
- The decision does not authorize inline indentation-column guides inside the main code text area as the primary first-wave solution.
- The decision does not authorize restoring the existing full stacked guide rendering as the default active-scope UX.
- The decision does not fix a specific visual palette or theme mapping.
- The decision does not yet define the exact serialized schema of the future structural-anchor surface; that belongs in plan/spec work derived from this decision.
- The decision does not require immediate availability of structural anchors to ship the first-wave `active container` and `active scope` gutter behavior.
## Revision Log
- 2026-04-03: Initial draft from AGD-0017.
- 2026-04-03: Accepted and split into execution plans PLN-0030, PLN-0031, and PLN-0032.