prometeu-studio/discussion/lessons/DSC-0021-studio-frontend-editor-write-and-save-wave/LSN-0036-vfs-owned-frontend-edit-and-save-wave.md

id	ticket	title	created	tags
LSN-0036	studio-frontend-editor-write-and-save-wave	VFS-Owned Frontend Edit and Save Wave	2026-04-06	studio editor frontend write save vfs lsp access-policy persistence

Context

The first editor write wave had deliberately kept frontend files hard read-only while semantic-read support shipped through prometeu-lsp. That left a controlled but incomplete product state:

• frontend documents already delivered semantic value,
• but editing and saving were still blocked,
• and the repository needed to decide whether that next wave would preserve or collapse the established ownership boundaries.

This discussion closed that transition by releasing frontend editing and save together under the existing VFS ownership model.

Key Decisions

Release Frontend Edit and Save in the Same Wave

What: Frontend editing and frontend save now ship together rather than as separate product steps.

Why: Editable-but-unsaveable frontend buffers would create a half-owned state and weaken the document boundary the repository had already stabilized.

Trade-offs: The first write release has to be coherent across access mode, dirty tracking, save, UI enablement, and specs. That is more coordinated work, but it avoids a broken intermediate product shape.

Keep prometeu-vfs as the Sole Document and Persistence Owner

What: prometeu-vfs remains the sole owner of frontend writable snapshots, access mode, dirty tracking, save, and save-all behavior. Studio UI consumes those rights, and prometeu-lsp continues to consume VFS-backed snapshots for semantics.

Why: The repository had already separated document ownership, semantic ownership, and UI consumption. Releasing frontend editing should not reopen that boundary.

Trade-offs: VFS carries more explicit frontend editing responsibility, and Studio must stay disciplined about consuming rather than deriving policy. That is preferable to splitting persistence logic across UI and semantic tooling layers.

Apply the First Write Wave to All Supported Frontend Files

What: The first frontend write wave applies to all currently supported frontend-scoped files recognized by the VFS/frontend boundary.

Why: The accepted decision explicitly rejected a temporary subset or per-file narrowing rule for this wave. Once frontend editing is released, the supported frontend scope should behave coherently.

Trade-offs: The wave requires confidence in the existing supported-file boundary. That is a better constraint than introducing new ad hoc file-class heuristics during rollout.

Final Implementation

The completed implementation propagated the decision across specs, VFS, and Studio:

• Studio specs now state that supported frontend-scoped documents may be editable when prometeu-vfs classifies them as editable and that semantic-read remains a consumer-only boundary.
• FilesystemVfsProjectDocument now classifies supported frontend documents as EDITABLE, accepts updateDocument, and persists them through saveDocument and saveAllDocuments.
• VFS tests now cover frontend editable access mode, in-memory mutation, save persistence, and save-all behavior.
• Studio editor session behavior now treats frontend editable files as ordinary VFS-authorized editable tabs rather than as hard read-only exceptions.
• Save and save-all continue to route through the existing VFS-owned path with no new persistence ownership in Studio UI or prometeu-lsp.

Patterns and Algorithms

Pattern: Release Mutation Together with Persistence

If a document class becomes editable, the same owner must also own save in the same release wave. Otherwise the product creates a draft-only state that undermines the document boundary.

Pattern: Keep UI as a Policy Consumer

The stable flow remains:

1. VFS classifies the document and exposes access context;
2. Studio enables editing and save based on that context;
3. LSP reads the same VFS-backed snapshots for semantics.

No layer needs to guess or duplicate ownership rules.

Example: Frontend Save Path

The resulting save flow is:

1. a supported frontend file opens through VFS as EDITABLE;
2. Studio mutates the VFS-owned in-memory snapshot;
3. save and save-all persist through VFS;
4. LSP continues reading the VFS-backed snapshot without becoming a persistence owner.

Pitfalls

• Do not release frontend editing without frontend save in the same wave.
• Do not move dirty tracking or persistence into Studio UI just because the editor hosts the interaction.
• Do not move access-policy or persistence ownership into prometeu-lsp.
• Do not introduce a narrowed temporary subset of supported frontend files without a new explicit decision.
• Do not let specs or UX surfaces keep describing frontend files as hard read-only after the wave has shipped.

References

• DEC-0019 Enable Frontend Editing and Save in the Studio Code Editor
• PLN-0040 Implement the frontend editor write and save wave through VFS ownership
• 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/EditorWorkspace.java
• prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorOpenFileSession.java

Takeaways

• Frontend editing is coherent only when save ownership lands in the same wave.
• VFS remains the right owner for access policy, dirty state, and persistence even for frontend documents.
• The architecture stays stable when Studio consumes policy and LSP consumes snapshots instead of either layer becoming a second document owner.