---
id: PLN-0020
ticket: studio-editor-write-wave-supported-non-frontend-files
title: Build DEC-0010 VFS access policy and save core
status: done
created: 2026-03-31
completed: 2026-03-31
tags: [studio, editor, vfs, write-wave, save, access-policy]
---

## Objective

Implement the VFS-side contract required by DEC-0010: canonical frontend scope, access policy classification, editable snapshots, and save-to-disk ownership.

## Background

DEC-0010 makes `prometeu-vfs` the owner of:

- frontend scope classification from `FrontendSpec.allowedExtensions`,
- canonical access policy per supported document,
- editable in-memory document snapshots for non-frontend supported text classes,
- and save persistence for those documents.

That work must land before editor UI code can consume the new write-wave behavior safely.

## Scope

### Included
- add VFS access-policy models
- evolve VFS document/type contract so frontend scope is canonical
- add snapshot mutation and save operations for editable non-frontend docs
- add the document-access context entity reserved by the decision
- update and expand VFS tests

### Excluded
- editor command-bar UI
- LSP API or semantic-read behavior
- frontend editing

## Execution Steps

### Step 1 - Extend the Public VFS API

**What:**
Add the public contract needed for access policy, editable snapshots, and save.

**How:**
Extend `prometeu-vfs-api` with:

- an explicit access-mode model,
- canonical frontend scope exposure through `typeId` or equivalent scope marker,
- document mutation/update operations for editable docs,
- save and save-all oriented commands,
- a document-access context entity that can be read and mutated now and persisted later.

**File(s):**
- `prometeu-vfs/prometeu-vfs-api/src/main/java/p/studio/vfs/**`

### Step 2 - Implement the Filesystem-Backed VFS Behavior

**What:**
Teach the filesystem-backed VFS to enforce DEC-0010 semantics.

**How:**
Update the VFS implementation so it:

- derives frontend scope from `FrontendSpec.allowedExtensions`,
- exposes canonical scope information through the VFS contract,
- rejects local mutation for hard `read-only` frontend docs,
- keeps editable non-frontend session snapshots in memory,
- persists those snapshots to disk on save.

**File(s):**
- `prometeu-vfs/prometeu-vfs-v1/src/main/java/p/studio/vfs/FilesystemProjectDocumentVfs.java`
- `prometeu-vfs/prometeu-vfs-v1/src/main/java/p/studio/vfs/FilesystemProjectDocumentVfsFactory.java`

### Step 3 - Add Conformance Tests

**What:**
Prove the VFS now owns the right boundary.

**How:**
Add tests that cover:

- frontend scope classification from `allowedExtensions`,
- hard `read-only` refusal for frontend docs,
- editable snapshots for non-frontend supported docs,
- save persistence,
- separation between editorial snapshots and fresh filesystem state where applicable,
- access-context lookup and mutation.

**File(s):**
- `prometeu-vfs/prometeu-vfs-v1/src/test/java/p/studio/vfs/FilesystemProjectDocumentVfsTest.java`
- new `prometeu-vfs/**` test files as needed

## Test Requirements

### Unit Tests
- access-policy classification
- frontend hard `read-only` behavior
- editable snapshot update/save behavior
- access-context read/mutate behavior

### Integration Tests
- filesystem-backed save roundtrip for editable non-frontend docs

### Manual Verification
- confirm editable non-frontend docs roundtrip through save
- confirm frontend docs stay non-mutable at the VFS boundary

## Acceptance Criteria

- [ ] VFS exposes canonical access policy for supported documents
- [ ] frontend scope derives from `FrontendSpec.allowedExtensions`
- [ ] frontend docs are hard `read-only` at the VFS boundary
- [ ] editable non-frontend docs have in-memory snapshots and save through VFS
- [ ] a single access-context entity exists for current read/mutate demand

## Dependencies

- DEC-0010 accepted
- PLN-0019 review completed or otherwise stable enough for implementation

## Risks

- overloading `typeId` incorrectly could break existing presentation routing
- save semantics could leak into frontend scope if access policy is not enforced centrally
- snapshot/context modeling could become too broad if it starts anticipating future LSP needs prematurely