prometeu-studio/discussion/workflow/plans/PLN-0020-build-dec-0010-vfs-access-policy-and-save-core.md

id	ticket	title	status	created	completed	tags
PLN-0020	studio-editor-write-wave-supported-non-frontend-files	Build DEC-0010 VFS access policy and save core	done	2026-03-31	2026-03-31	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