housekeep

This commit is contained in:
2026-04-06 04:39:27 +01:00
parent 770aa6a387
commit 5871243f8f
19 changed files with 390 additions and 1790 deletions
@@ -1,147 +0,0 @@
---
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.
@@ -1,160 +0,0 @@
---
id: DEC-0015
ticket: studio-editor-inline-type-hints-for-let-bindings
title: Studio Editor Inline Type Hints Contract and Rendering Model
status: accepted
created: 2026-04-03
accepted: 2026-04-03
agenda: AGD-0018
plans: [PLN-0033, PLN-0034, PLN-0035, PLN-0036]
tags: [studio, editor, inline-hints, inlay-hints, lsp, frontend-contract, type-inference]
---
## Decision
O Studio SHALL support inline type hints as a first-class editor capability rather than as a PBS-only exception.
The ownership model for the capability is normatively locked as follows:
- the frontend MUST define which hints exist, where they anchor, and what semantic payload they carry;
- the LSP MUST define and enforce the transport contract for those hints and MUST transport frontend-produced hint data to the Studio consumer;
- the Studio MUST render transported hints and MUST NOT invent frontend hint content on its own.
The final user-visible form of the feature MUST be real inline rendering inside the editor flow.
Any approximate visual solution MAY be used only as a transitional implementation stage and MUST be explicitly treated as an intermediate rollout step rather than as the final contract.
Inline hints produced under this capability MUST be decorative only.
Inline hints MUST NOT:
- mutate document text;
- participate as document content in copy/paste;
- redefine selection semantics;
- redefine caret movement semantics;
- become part of the persisted file model.
When analysis is partially degraded, the Studio MUST preserve and render hint spans that remain valid under the transported contract rather than disabling all hints for the whole document.
The host policy for what receives hints is frontend-owned.
If a frontend publishes valid hints under the LSP contract, the Studio MUST render them.
If a frontend does not publish a hint for a construct, the Studio MUST NOT synthesize one.
## Rationale
This decision separates semantic ownership from host rendering responsibility in the same disciplined way already adopted for frontend semantic presentation.
The chosen split avoids two failure modes:
1. Studio-owned hint content, which would duplicate frontend semantics and make the editor a second semantic authority;
2. frontend-specific rendering logic inside the Studio host, which would make the editor harder to generalize and maintain.
The decision also prevents a common product regression: shipping an approximate overlay and silently letting it become the permanent implementation.
By locking inline real rendering as the required final state, the repository preserves the intended UX target while still allowing phased execution.
Decorative-only hints keep the document model stable and avoid corrupting editing semantics.
Partial degradation tolerance follows the same operational direction already desired for editor highlighting: valid local semantic signal should survive even when the full-document analysis path is degraded.
## Technical Specification
### 1. Capability Model
The editor hint system MUST be implemented as a host capability named conceptually equivalent to inline or inlay hints.
That capability MUST be host-generic and MUST NOT be modeled as a PBS-only feature.
### 2. Ownership Boundary
Frontend responsibilities:
- define whether a hint exists;
- define the semantic meaning of the hint;
- define the anchor location or anchor span;
- define the payload required for rendering, including display text and any semantic category needed by the contract.
LSP responsibilities:
- define the DTO and transport contract consumed by the Studio;
- validate and transport frontend-produced hint payloads;
- preserve enough anchoring information for deterministic host rendering;
- avoid inventing host-owned semantic meaning not present in frontend-produced hint data.
Studio responsibilities:
- render transported hints;
- apply host styling and layout behavior;
- keep hints visually separate from document text;
- preserve editor document semantics and editing behavior.
### 3. Content Policy
The Studio MUST treat hint presence as frontend-authoritative.
The Studio MUST render valid transported hints regardless of the frontend that produced them.
The Studio MUST NOT hardcode rules such as:
- hint all `let` declarations by host policy;
- suppress frontend-provided hints because the host prefers a different policy;
- create fallback semantic hints not present in the contract.
### 4. Rendering Model
The feature is only considered complete when hints are rendered inline in the editor flow as non-textual host decorations attached to document positions.
An approximate visual stage MAY exist temporarily if needed to de-risk delivery, but:
- it MUST be documented as transitional;
- it MUST NOT redefine the final contract;
- subsequent plans MUST converge explicitly to real inline rendering.
### 5. Interaction Model
Hints are decorative only.
Therefore the implementation MUST ensure:
- persisted source text remains unchanged;
- selection ranges are computed over document text only;
- caret movement is computed over document text only;
- copy/paste operates on document text only;
- hint visibility does not alter the canonical file buffer.
### 6. Partial Degradation
When semantic analysis yields only partial valid hint data:
- valid hint spans MUST continue to render;
- invalid or missing spans MAY be omitted locally;
- the Studio MUST NOT disable all hints for the entire document solely because some hint spans could not be produced.
### 7. Initial Scope
This decision is initiated by the PBS need to show inferred type hints for local bindings such as `let`.
However, this decision does not lock hint eligibility to `let`.
Eligibility remains frontend-owned under the contract above.
### 8. Propagation Targets
This decision MUST be propagated to:
- Studio editor specifications covering editor rendering and semantic read surfaces;
- LSP specifications or contracts covering semantic transport payloads;
- implementation plans for frontend hint payload production, LSP transport, and Studio rendering;
- tests covering decorative behavior, anchor stability, partial degradation, and frontend-owned hint policy.
## Constraints
- No implementation plan may reinterpret Studio as semantic owner of hint content.
- No implementation plan may treat an approximate overlay as the final shipped architecture.
- No implementation plan may allow hints to become part of the editable document text model.
- If a later plan discovers that the current editor substrate cannot support inline real rendering cleanly, that plan MUST surface the substrate limitation explicitly and propose the required editor primitive or migration path rather than silently downgrading the final requirement.
## Revision Log
- 2026-04-03: Initial accepted decision from AGD-0018.
@@ -1,125 +0,0 @@
---
id: DEC-0019
discussion: DSC-0021
agenda: AGD-0022
ticket: studio-frontend-editor-write-and-save-wave
title: Enable Frontend Editing and Save in the Studio Code Editor
status: accepted
created: 2026-04-04
updated: 2026-04-04
owner: studio
tags: [studio, editor, frontend, write, save, vfs, lsp, pbs, access-policy]
---
## Context
Studio already provides frontend semantic-read value through `prometeu-lsp`, while frontend documents remain hard `read-only`.
The repository also already locked the architectural split between document ownership and semantic ownership:
1. `prometeu-vfs` owns document classification, access mode, snapshots, and save behavior;
2. `prometeu-lsp` consumes VFS-backed snapshots for semantic analysis;
3. Studio UI consumes both boundaries and must not re-derive document rights locally.
The previous semantic-read wave explicitly stated that frontend editing requires a separate decision.
This decision closes that gap.
## Decision
Studio SHALL release frontend editing and frontend save together in one explicit write wave.
The wave is normatively defined as follows:
1. Frontend editing MUST NOT be released without frontend save in the same wave.
2. `prometeu-vfs` MUST remain the sole owner of frontend writable snapshots.
3. `prometeu-vfs` MUST remain the sole owner of frontend access mode.
4. `prometeu-vfs` MUST remain the sole owner of frontend dirty tracking.
5. `prometeu-vfs` MUST remain the sole owner of frontend save and save-all behavior.
6. Studio UI MUST consume frontend editability and save rights from `prometeu-vfs` rather than introducing editor-local policy.
7. `prometeu-lsp` MUST continue as a semantic consumer of VFS-backed frontend snapshots, including dirty in-memory frontend state.
8. This decision does NOT authorize a new LSP implementation wave as part of the immediate execution scope.
9. The first frontend write wave MUST apply to all frontend-scoped supported files and MUST NOT introduce an additional narrowing rule in this wave.
10. Releasing frontend editing MUST NOT collapse semantic ownership, document ownership, and persistence ownership into one module.
## Rationale
Frontend mutation without frontend save would create a half-owned editorial state and weaken the document boundary that the repository has already stabilized.
The correct release shape is therefore coherent FE mutation plus coherent FE persistence under the same owner.
Keeping `prometeu-vfs` as the sole owner preserves the existing architecture:
- VFS owns documents and persistence;
- LSP consumes document state for semantics;
- UI renders and interacts with policy.
This decision also avoids using a fake transitional step where the editor mutates frontend text locally while persistence remains undefined.
## Technical Specification
### Frontend Document Ownership
Frontend-scoped supported files MUST move from hard `read-only` to editable only through `prometeu-vfs`.
That means:
1. writable FE in-memory snapshots MUST be created and owned by VFS;
2. FE dirty tracking MUST be owned by VFS;
3. FE save and save-all MUST route through VFS;
4. editor-visible FE access mode MUST be surfaced from VFS.
### Editor Behavior
The Studio editor MUST consume the new FE access policy from VFS exactly as it already does for non-frontend editable documents.
The editor MUST NOT:
1. create a separate FE-only mutation model;
2. implement FE-local persistence outside VFS;
3. infer FE save rights through UI heuristics.
### LSP Consumption Boundary
`prometeu-lsp` remains authorized to consume dirty FE snapshots from VFS.
However, this decision does not authorize a new LSP feature wave as part of immediate execution.
Immediate implementation may rely on the existing semantic-read seam, provided that:
1. no new persistence ownership moves into LSP;
2. no new access-policy ownership moves into LSP;
3. FE write enablement does not depend on introducing a new LSP-owned document model.
### Scope of First FE Write Wave
The first FE write wave applies to all frontend-scoped supported files currently recognized by the VFS/frontend boundary.
This decision does not authorize:
1. a temporary subset of FE file classes;
2. an editor-only FE draft mode;
3. FE edit rights without FE save rights.
## Constraints
1. This decision does not authorize a new LSP implementation scope by itself.
2. This decision does not authorize moving document state ownership into Studio UI.
3. This decision does not authorize moving document state ownership into LSP.
4. This decision does not authorize releasing FE editing through a separate temporary persistence path.
## Propagation Targets
- Specs:
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `docs/specs/studio/6. Project Document VFS Specification.md`
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
- Plans:
- FE VFS write/access/save propagation
- Studio FE editor access-mode and save UX propagation
- Code:
- `prometeu-vfs` FE writable snapshot and save policy
- `prometeu-studio` FE editor write UX and access-state propagation
- Tests:
- FE VFS access-mode and save coverage
- FE editor editable/saveable behavior
## Revision Log
- 2026-04-04: Accepted from `AGD-0022` to release FE editing and save together under VFS ownership, with no new immediate LSP implementation scope.