---
id: LSN-0036
ticket: studio-frontend-editor-write-and-save-wave
title: VFS-Owned Frontend Edit and Save Wave
created: 2026-04-06
tags: [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.
