---
id: PLN-0016
ticket: studio-editor-document-vfs-boundary
title: Build the filesystem-backed `prometeu-vfs` core for project tree and documents
status: review
created: 2026-03-31
completed:
tags:
  - studio
  - vfs
  - filesystem
  - rpc
  - module
---

## Briefing

Create the first `prometeu-vfs` module implementation as a filesystem-backed project-document core that carries only the current Code Editor capabilities.

## Objective

Introduce a testable `prometeu-vfs` module that owns structural project snapshots, document loading, support classification, and manual refresh operations for project content.

## Background

The current editor owns three separate local responsibilities:

- project tree snapshot building
- file buffer loading and unsupported-file classification
- session-local opened-file coordination

DEC-0009 moves the first two responsibilities into `prometeu-vfs` while preserving the current functional surface and deferring watchers, public events, and write semantics.

## Dependencies

- DEC-0009 accepted and normatively locked
- PLN-0015 accepted or otherwise completed enough to make the target spec language stable

## Scope

### Included

- add the new Gradle module wiring for `prometeu-vfs`
- define the initial RPC-oriented public API for project tree and document access
- implement a filesystem-backed first version
- move file support classification into `prometeu-vfs`
- add unit tests that cover the new module behavior

### Excluded

- project-session ownership in Studio bootstrap
- workspace UI changes beyond dependency wiring needed for compilation
- public event API exposure
- watchers
- save, dirty tracking, writes, merge handling, or conflict handling
- non-project content snapshots

## Non-Goals

- create a general VFS for packer, assets, or debugger
- redesign the editor session model
- introduce a second backend beyond filesystem

## Execution Method

### Step 1 - Add `prometeu-vfs` to the Gradle Workspace

**What:**
Make the new module part of the build and available to Studio code.

**How:**
Update the root Gradle settings and module dependencies so the Studio can compile against `prometeu-vfs`.

**File(s):**
- `settings.gradle.kts`
- `prometeu-studio/build.gradle.kts`
- new `prometeu-vfs/**`

### Step 2 - Define the Initial RPC-Oriented Contract

**What:**
Create the public API surface for structural tree retrieval, point refresh requests, document resolution, and support classification.

**How:**
Define models and service interfaces in `prometeu-vfs` for:

- project-scoped tree snapshots
- structural tree nodes
- document open/load results
- unsupported-file or unsupported-handler outcomes
- manual refresh commands, including targeted refresh requests for narrower scope than full reload

The API must remain RPC-oriented and must not expose public events in this wave.

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

### Step 3 - Implement the Filesystem-Backed First Version

**What:**
Move direct filesystem behavior out of editor-local services and into `prometeu-vfs`.

**How:**
Implement the first module version using filesystem access for:

- full-project structural snapshot construction
- folder-first alphabetical ordering
- project-only scope
- UTF-8 text loading
- binary or unsupported-file rejection
- support-rule evaluation

Port the logic now living in:

- `EditorProjectSnapshotService`
- `EditorFileBufferLoader`

without adding new end-user behavior.

**File(s):**
- new `prometeu-vfs/src/main/java/p/studio/vfs/**`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshotService.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorFileBufferLoader.java`

### Step 4 - Move Core Tests to the Module Boundary

**What:**
Place structural snapshot and document-loading tests at the new ownership boundary.

**How:**
Port and expand the current editor service tests into `prometeu-vfs` module tests, covering:

- hidden file inclusion
- folder-first ordering
- project-only root handling
- unsupported file outcomes
- UTF-8 and NUL-byte handling
- targeted refresh request behavior

**File(s):**
- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorProjectSnapshotServiceTest.java`
- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorFileBufferLoaderTest.java`
- new `prometeu-vfs/src/test/java/p/studio/vfs/**`

## Test Requirements

### Unit Tests

- structural tree snapshot coverage
- document load and unsupported-file coverage
- targeted refresh request coverage
- project-only scope coverage

### Integration Tests

- module-level integration test that builds a snapshot and resolves documents from a test project root

### Manual Verification

- verify the module can build against Studio without introducing UI dependencies
- verify no public event API leaks into the first-wave contract

## Acceptance Criteria

- [ ] the build contains a new `prometeu-vfs` module wired into Studio
- [ ] project tree and document loading behavior now exist in `prometeu-vfs`
- [ ] the public contract is RPC-oriented and does not expose public events
- [ ] unsupported-file classification is owned by `prometeu-vfs`
- [ ] module tests cover the current editor-visible filesystem behavior

## Affected Artifacts

- `settings.gradle.kts`
- `prometeu-studio/build.gradle.kts`
- new `prometeu-vfs/**`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshotService.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorFileBufferLoader.java`
- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorProjectSnapshotServiceTest.java`
- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorFileBufferLoaderTest.java`

## Risks

- overfitting the first API to current editor internals could make later Studio and LSP consumers awkward
- keeping too much logic in the editor during migration would weaken the ownership boundary
- adding too much abstraction now would violate the first-wave scope limit