prometeu-studio/discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md

id	ticket	title	created	tags
LSN-0027	studio-editor-document-vfs-boundary	Project Document VFS and Session-Owned Editor Boundary	2026-03-31	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.