135 lines
7.9 KiB
Markdown
135 lines
7.9 KiB
Markdown
---
|
|
id: LSN-0028
|
|
ticket: studio-editor-write-wave-supported-non-frontend-files
|
|
title: Controlled Editor Write Wave and Read-Only Frontend Semantic Phase
|
|
created: 2026-04-02
|
|
tags: [studio, editor, vfs, lsp, access-policy, save, read-only, frontend-boundary]
|
|
---
|
|
|
|
## Context
|
|
|
|
The first Studio `Code Editor` implementation had already established a session-owned document boundary through `prometeu-vfs`, but it was still missing the next operational split:
|
|
|
|
- which supported files could become editable now,
|
|
- which files had to remain hard `read-only`,
|
|
- where save ownership lived,
|
|
- and how frontend semantic value could ship before frontend editing rights.
|
|
|
|
This discussion closed that split in two coordinated decisions.
|
|
The result is a deliberately mixed editor phase:
|
|
|
|
- supported non-frontend textual documents can be edited and saved,
|
|
- frontend-scoped documents stay hard `read-only`,
|
|
- and frontend semantic features arrive through `prometeu-lsp` as a consumer of VFS snapshots rather than as a new document owner.
|
|
|
|
## Key Decisions
|
|
|
|
### Keep Access Policy and Save Ownership in `prometeu-vfs`
|
|
|
|
**What:**
|
|
`prometeu-vfs` is the canonical owner of document access mode, canonical `typeId`, editable in-memory snapshots, save, and save-all behavior for the first write wave.
|
|
|
|
**Why:**
|
|
The editor workspace needs to consume policy, not recreate it.
|
|
If editability, frontend classification, or save rules drift into Studio UI code, the product loses the project-document boundary that earlier work had just established.
|
|
|
|
**Trade-offs:**
|
|
This adds explicit VFS contract surface for access context, document mutation, and save orchestration.
|
|
That extra structure is intentional because it prevents editor-local heuristics from becoming product behavior.
|
|
|
|
### Release a Narrow Write Wave Instead of Universal Editing
|
|
|
|
**What:**
|
|
The editable set is intentionally limited to already-supported non-frontend textual classes: `text`, `json`, `ndjson`, and `bash`.
|
|
Frontend-scoped files stay hard `read-only` in the same workspace.
|
|
|
|
**Why:**
|
|
Not every supported text file belongs to the same product tier.
|
|
Frontend files carry language-owned semantics and future editing constraints that were not ready to ship in the same wave as generic project documents.
|
|
|
|
**Trade-offs:**
|
|
The editor becomes mixed-mode immediately, which requires clearer UX for save enablement, status-bar access state, and frontend warnings.
|
|
That is preferable to pretending all supported documents can be treated uniformly.
|
|
|
|
### Introduce Frontend Semantic Read Before Frontend Edit Rights
|
|
|
|
**What:**
|
|
`prometeu-lsp` was introduced as a semantic consumer above `prometeu-vfs` for frontend diagnostics, symbols, outline structure, definition, and semantic highlight while frontend files remain hard `read-only`.
|
|
|
|
**Why:**
|
|
Semantic readiness and editing rights should not be released together by default.
|
|
The semantic-read phase provides real value for frontend files without collapsing access policy, persistence, and semantic analysis into a single owner.
|
|
|
|
**Trade-offs:**
|
|
The system now has one more module boundary and one more contract seam to maintain.
|
|
That cost is lower than releasing frontend mutation before the semantic substrate and ownership boundaries are stable.
|
|
|
|
## Final Implementation
|
|
|
|
The final implementation landed across specs, VFS, LSP, and Studio UI:
|
|
|
|
- `docs/specs/studio/5. Code Editor Workspace Specification.md` now defines the mixed editable and hard `read-only` editor wave, editor-local `Save` and `Save All`, frontend warning surfaces, and the frontend semantic-read phase.
|
|
- `docs/specs/studio/6. Project Document VFS Specification.md` now makes `FrontendSpec.allowedExtensions` the source of truth for frontend scope, defines canonical `typeId` and access-mode ownership, and keeps editorial snapshots separate from build-facing state.
|
|
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md` now defines the minimum frontend semantic-read phase and the flat public packaging expectations for `prometeu-lsp`.
|
|
- `FilesystemVfsProjectDocument` classifies supported documents as editable or hard `read-only`, keeps editable in-memory snapshots, rejects mutation for hard `read-only` frontend documents, and persists editable snapshots through save operations.
|
|
- `prometeu-lsp` now exposes a concrete semantic-read service layer for diagnostics, symbols, definition, and frontend highlight consumption over VFS-backed session state.
|
|
- `EditorWorkspace`, `EditorOpenFileSession`, `EditorStatusBar`, and related UI surfaces now consume VFS access policy, expose editor-local save actions, and render mixed editable and frontend `read-only` tabs coherently.
|
|
|
|
## Patterns and Algorithms
|
|
|
|
### Pattern: Make the Editor a Policy Consumer
|
|
|
|
The correct ownership split is:
|
|
|
|
- `prometeu-vfs` decides supported document classification, access mode, snapshot ownership, and save behavior;
|
|
- `prometeu-lsp` consumes VFS-backed document state for semantic analysis;
|
|
- Studio UI consumes both boundaries for presentation and interaction.
|
|
|
|
This keeps each layer honest about its owner role.
|
|
|
|
### Pattern: Ship Semantic Value Before Edit Rights
|
|
|
|
When language-owned files need semantic support before mutation support, introduce a semantic-read phase instead of unlocking editing prematurely.
|
|
That pattern gives diagnostics, navigation, and semantic presentation without forcing save, dirty tracking, or mutation policy into a half-ready frontend phase.
|
|
|
|
### Example: Mixed-Mode Editor Flow
|
|
|
|
The resulting flow is:
|
|
|
|
1. `prometeu-vfs` opens a supported document and returns canonical `typeId` plus access context.
|
|
2. Studio opens the tab and renders editable or hard `read-only` state from that policy.
|
|
3. Editable non-frontend documents mutate session-owned snapshots and save through editor-local actions.
|
|
4. Frontend documents remain non-mutable, show explicit warning and status surfaces, and may still receive semantic diagnostics, symbols, definition, and highlight through `prometeu-lsp`.
|
|
|
|
## Pitfalls
|
|
|
|
- Do not let Studio UI re-derive frontend scope from file extensions or path heuristics; `FrontendSpec.allowedExtensions` must stay behind the VFS boundary.
|
|
- Do not treat editorial in-memory snapshots as canonical build input just because LSP can analyze them.
|
|
- Do not let `prometeu-lsp` absorb save, persistence, or access-policy ownership.
|
|
- Do not silently expand editable scope beyond `text`, `json`, `ndjson`, and `bash` without a new explicit decision.
|
|
- Do not release frontend editing just because frontend semantic highlight and definition already exist.
|
|
|
|
## References
|
|
|
|
- `DEC-0010` Establish the controlled non-frontend editor write wave in Studio
|
|
- `DEC-0011` Establish the frontend read-only minimum LSP phase in Studio
|
|
- `PLN-0019` Propagate DEC-0010 into Studio editor and VFS specs
|
|
- `PLN-0020` Build DEC-0010 VFS access policy and save core
|
|
- `PLN-0021` Integrate DEC-0010 editor write UI and workflow in Studio
|
|
- `PLN-0022` Propagate DEC-0011 into Studio, VFS, and LSP specs
|
|
- `PLN-0023` Scaffold flat-packed prometeu-lsp API and Studio session seams
|
|
- `PLN-0024` Implement read-only FE diagnostics, symbols, and definition over VFS snapshots
|
|
- `PLN-0025` Implement FE semantic highlight and editor consumption for the read-only LSP phase
|
|
- `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`
|
|
- `prometeu-vfs/prometeu-vfs-v1/src/main/java/p/studio/vfs/FilesystemVfsProjectDocument.java`
|
|
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspServiceImpl.java`
|
|
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
|
|
|
|
## Takeaways
|
|
|
|
- A mixed editable plus hard `read-only` editor wave is viable when access policy stays centralized in VFS.
|
|
- Semantic-read support is a separate product phase from frontend edit rights and should be modeled that way.
|
|
- Save ownership, semantic consumption, and UI presentation stay cleaner when `prometeu-vfs`, `prometeu-lsp`, and Studio each keep a narrow role.
|