prometeu-studio/discussion/workflow/plans/PLN-0040-studio-frontend-editor-write-and-save-wave.md

id	discussion	decision	ticket	title	status	created	updated	owner	tags
PLN-0040	DSC-0021	DEC-0019	studio-frontend-editor-write-and-save-wave	Implement the frontend editor write and save wave through VFS ownership	done	2026-04-04	2026-04-04	studio	studio editor frontend write save vfs lsp pbs access-policy

Briefing

Implement the accepted frontend write wave for the Studio Code Editor. Frontend editing and frontend save must be released together, must remain owned by prometeu-vfs, and must be consumed by Studio UI without introducing a new immediate LSP implementation wave.

Objective

Move frontend-scoped supported files from hard read-only to VFS-owned editable/saveable documents while preserving the current boundary:

• prometeu-vfs owns document state and persistence;
• prometeu-lsp remains a semantic consumer of VFS-backed snapshots;
• Studio UI remains a policy consumer.

Dependencies

• DEC-0019 Enable Frontend Editing and Save in the Studio Code Editor
• existing prometeu-vfs editable snapshot and save model for non-frontend textual documents
• existing Studio editor consumption of VFS access mode and save behavior
• existing semantic-read seam where prometeu-lsp reads VFS-backed frontend snapshots

Scope

• propagate the new FE write/save contract into Studio and VFS specs
• extend prometeu-vfs so frontend-scoped supported files become editable/saveable
• keep FE writable snapshots, dirty tracking, and save ownership inside VFS
• update Studio editor behavior to consume FE editability from VFS
• update FE write/save tests in VFS and Studio

Non-Goals

• any new LSP feature implementation wave
• per-file FE access policy
• partial FE draft mode without save
• moving persistence logic into Studio UI
• moving persistence logic into prometeu-lsp

Execution Method

1. Propagate the accepted contract into specs

Update the Studio specs that still describe FE files as hard read-only so they now describe the new FE write/save wave and preserve VFS ownership plus semantic-consumer-only LSP ownership.

Targets:

• 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

2. Change FE access policy in prometeu-vfs

Update the filesystem-backed VFS classification so frontend-scoped supported files become EDITABLE rather than READ_ONLY, while preserving frontend classification itself.

What changes:

• document kind classification for FE files
• VFS acceptance of FE updateDocument
• VFS save/save-all behavior for FE snapshots
• FE dirty tracking semantics under the same VFS owner model already used for editable non-frontend documents

Targets:

• prometeu-vfs/prometeu-vfs-v1/src/main/java/p/studio/vfs/FilesystemVfsProjectDocument.java
• any supporting VFS API contracts if required by the implementation

Dependency ordering:

• this step must land before Studio editor UX changes so the UI can consume the new policy rather than invent it.

3. Update VFS tests for FE edit/save behavior

Replace tests that assert FE hard read-only behavior with tests that assert:

1. FE documents open as frontend documents with EDITABLE access mode;
2. FE documents accept updateDocument;
3. FE documents save correctly through saveDocument;
4. FE documents participate correctly in saveAllDocuments.

Targets:

• prometeu-vfs/prometeu-vfs-v1/src/test/java/p/studio/vfs/FilesystemVfsProjectDocumentTest.java

4. Propagate FE editability into the Studio editor

Update the Studio editor to consume the new FE access mode from VFS exactly as it already does for editable non-frontend documents.

What changes:

• FE tabs become editable when VFS reports EDITABLE
• FE warning surfaces that are specific to hard read-only FE behavior must be revised or removed
• editor save/save-all enablement must work for dirty FE buffers through the existing VFS-backed flow
• no FE-local persistence path may be introduced

Targets:

• prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java
• prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorStatusBar.java
• any FE-warning or editor-session support classes affected by access-mode transition

Dependency ordering:

• this step depends on VFS access-mode propagation from Step 2.

5. Keep LSP integration stable without opening new implementation scope

Verify that the existing editor and semantic-read flow still calls prometeu-lsp as a consumer of FE snapshots, but do not introduce a new LSP implementation wave.

What changes:

• only compatibility adjustments that are strictly necessary because FE snapshots are now editable may be made;
• no new semantic features, refresh model, or ownership expansion is authorized here.

Targets:

• only the minimum compatibility surface if compilation or existing tests require it

Dependency ordering:

• this is verification-oriented and should follow the VFS/editor write changes.

6. Update Studio tests for FE editable/saveable behavior

Add or revise editor tests so they assert FE files are no longer treated as permanently hard read-only once VFS grants FE EDITABLE access mode.

Targets:

• Studio editor tests under prometeu-studio/src/test/java/p/studio/workspaces/editor/...
• any session/editor tests affected by FE access-mode transition

Acceptance Criteria

1. Frontend-scoped supported files open through VFS with EDITABLE access mode.
2. Frontend-scoped supported files can be updated and saved through VFS-owned snapshots.
3. Studio editor FE tabs become editable only because VFS reports them as editable.
4. FE save and save-all route through the same VFS owner path used by other editable documents.
5. No new persistence or access-policy ownership moves into Studio UI.
6. No new persistence or access-policy ownership moves into prometeu-lsp.
7. Specs no longer describe FE files as hard read-only for the current wave.

Tests

• VFS tests for FE access mode, update, save, and save-all
• Studio editor tests for FE editable/saveable behavior
• regression tests that confirm non-frontend editable documents still behave correctly
• compile/test verification that existing LSP consumer seams still pass without opening new LSP feature scope

Affected Artifacts

• discussion/workflow/decisions/DEC-0019-studio-frontend-editor-write-and-save-wave.md
• 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-vfs/prometeu-vfs-v1/src/test/java/p/studio/vfs/FilesystemVfsProjectDocumentTest.java
• prometeu-studio/src/main/java/p/studio/workspaces/editor/...
• Studio editor tests

Risks

• existing specs and tests currently encode the old hard read-only FE contract and will fail until all propagation lands coherently
• FE warning/UI surfaces may assume old read-only semantics in more than one place
• LSP snapshot consumption could reveal hidden assumptions about FE immutability even without opening a new LSP scope
• if implementation order is reversed and Studio is changed before VFS policy, UI code may drift into local heuristics