prometeu-studio/discussion/workflow/plans/PLN-0016-build-prometeu-vfs-filesystem-backed-core.md

id	ticket	title	status	created	completed	tags
PLN-0016	studio-editor-document-vfs-boundary	Build the filesystem-backed `prometeu-vfs` core for project tree and documents	done	2026-03-31	2026-03-31	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