---
id: LSN-0027
ticket: studio-editor-document-vfs-boundary
title: Project Document VFS and Session-Owned Editor Boundary
created: 2026-03-31
tags: [studio, editor, vfs, project-session, filesystem, boundary, architecture]
---

## Context

The first Studio `Code Editor` wave had already established a read-only editorial shell, but the concrete implementation still let the editor package own direct filesystem concerns for:

- building the project tree,
- opening documents,
- classifying supported files,
- and refreshing project state.

That structure was workable for a first slice, but it created the wrong long-term owner.
If the editor shell continued to own those concerns, future document overlays, refresh coordination, or additional consumers such as `prometeu-lsp` would have been forced to grow around editor-local filesystem helpers instead of a real project-document boundary.

## Key Decisions

### Introduce `prometeu-vfs` as the Studio Project-Document Boundary

**What:**
The repository now treats `prometeu-vfs` as the module that owns project-tree snapshots, project document opening, support classification, and manual refresh for the Studio editor flow.

**Why:**
Those are project-document runtime concerns, not workspace-layout concerns.
Moving them into a dedicated boundary keeps the editor focused on UI composition, open-tab presentation, and error rendering.

**Trade-offs:**
This adds a new module boundary and more explicit contracts up front.
That extra structure is intentional because it stops the editor package from becoming an accidental filesystem runtime.

### Make the Boundary Session-Owned Instead of Workspace-Owned

**What:**
`prometeu-vfs` is owned by a Studio project session and passed into the editor, instead of being created and destroyed by `EditorWorkspace` focus or composition.

**Why:**
Document state belongs to the opened project window, not to the currently focused workspace tab.
This preserves the correct lifecycle for future editor expansion without making the shell re-create document state on workspace switches.

**Trade-offs:**
Studio needed a small project-session abstraction, but that cost is lower than letting per-project state leak into shell-global or workspace-local ownership.

### Keep the First Wave Narrow and RPC-Oriented

**What:**
The first `prometeu-vfs` surface stays filesystem-backed, project-scoped, and RPC-oriented.
It intentionally excludes public event APIs, watchers, write semantics, and non-project content.

**Why:**
The decision was to stabilize the ownership boundary first, not to solve every future document-runtime concern in one pass.

**Trade-offs:**
The first API is narrower than a full document platform.
That is a feature, because it keeps the migration disciplined and prevents accidental scope growth.

## Final Implementation

The final implementation established the new boundary across specs and code:

- `settings.gradle.kts` now includes `prometeu-vfs:prometeu-vfs-api` and `prometeu-vfs:prometeu-vfs-v1`.
- `docs/specs/studio/6. Project Document VFS Specification.md` defines the normative boundary, including project-session ownership, structural tree rules, RPC-first API rules, manual refresh, and the explicit exclusion of watchers and public events.
- `ProjectDocumentVfs` became the public project-document contract for snapshot, targeted refresh, and document opening.
- `FilesystemProjectDocumentVfs` became the first filesystem-backed implementation of that contract.
- `StudioProjectSession` and `StudioProjectSessionFactory` now own the project-scoped VFS lifecycle.
- `MainView` passes the session-owned VFS into `EditorWorkspace`.
- `EditorWorkspace` consumes the VFS instead of owning direct filesystem tree and document loaders.

## Patterns and Algorithms

### Pattern: Separate Structural Data Ownership from Visual Tree Ownership

The correct split is:

- `prometeu-vfs` owns structural project data and document resolution;
- Studio UI owns visual state such as expansion, focus, selection, reveal behavior, and iconography.

This keeps the navigator honest: it renders project data, but it does not redefine document-runtime ownership.

### Pattern: Put Per-Project Runtime Under a Session Object

When state must survive workspace focus changes but remain scoped to one opened project, introduce a project-session owner.
That pattern is cleaner than making the workspace itself own the state or pushing project state into a global container.

### Example: Editor Consumption Flow

The new flow is:

1. a Studio project session opens;
2. the session constructs `prometeu-vfs`;
3. `MainView` passes the session-owned dependency to `EditorWorkspace`;
4. the editor asks `prometeu-vfs` for snapshots, targeted refreshes, and document opens;
5. the editor still owns tabs, layout, and UI reactions.

## Pitfalls

- Do not let `prometeu-vfs` start absorbing visual tree state just because the navigator consumes its data.
- Do not recreate `prometeu-vfs` on workspace focus switches; that would collapse the session boundary back into the editor shell.
- Do not infer watchers, public events, save semantics, or dirty tracking from the existence of the new boundary.
- Do not let other domains treat `prometeu-vfs` as a universal filesystem layer without a new explicit decision.

## References

- `DEC-0009` Establish `prometeu-vfs` as the project-document boundary for Studio
- `PLN-0015` Propagate DEC-0009 into Studio shell, editor, and VFS specs
- `PLN-0016` Build the filesystem-backed `prometeu-vfs` core for project tree and documents
- `PLN-0017` Add Studio project-session ownership for `prometeu-vfs`
- `PLN-0018` Migrate the Code Editor workspace to consume `prometeu-vfs`
- `docs/specs/studio/6. Project Document VFS Specification.md`
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `prometeu-vfs/prometeu-vfs-api/src/main/java/p/studio/vfs/ProjectDocumentVfs.java`
- `prometeu-vfs/prometeu-vfs-v1/src/main/java/p/studio/vfs/FilesystemProjectDocumentVfs.java`
- `prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSession.java`
- `prometeu-studio/src/main/java/p/studio/window/MainView.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`

## Takeaways

- A code editor should consume a project-document boundary, not become one.
- Project-document runtime state belongs to the project session, not to workspace focus.
- A narrow filesystem-backed VFS is a strong first step when the goal is to stabilize ownership before adding richer editor behavior.
