---
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.
