prometeu-studio/discussion/lessons/DSC-0013-studio-editor-write-wave-supported-non-frontend-files/LSN-0028-controlled-editor-write-wave-and-read-only-frontend-semantic-phase.md

id	ticket	title	created	tags
LSN-0028	studio-editor-write-wave-supported-non-frontend-files	Controlled Editor Write Wave and Read-Only Frontend Semantic Phase	2026-04-02	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.