prometeu-studio/discussion/workflow/plans/PLN-0017-add-studio-project-session-ownership-for-prometeu-vfs.md

id	ticket	title	status	created	completed	tags
PLN-0017	studio-editor-document-vfs-boundary	Add Studio project-session ownership for `prometeu-vfs`	done	2026-03-31	2026-03-31	studio vfs project-session shell lifecycle

Briefing

Move prometeu-vfs ownership into the Studio project session so document state survives workspace focus changes and is not owned by EditorWorkspace.

Objective

Create a project-session integration path in Studio that constructs, passes, and disposes prometeu-vfs state outside workspace focus transitions.

Background

DEC-0009 requires prometeu-vfs to live at project-session scope rather than editor-workspace scope. The current project-open path builds a MainView directly from ProjectReference and has no dedicated project-session service layer for editor document runtime state.

Dependencies

• DEC-0009 accepted and normatively locked
• PLN-0016 accepted or otherwise completed enough to provide the prometeu-vfs contract

Scope

Included

• add a Studio-side project-session owner for prometeu-vfs
• construct that session during project open
• keep the session alive while the project window is open
• dispose the session when the project window closes
• pass the session or a focused prometeu-vfs facade down to MainView and workspace consumers

Excluded

• editor behavior changes beyond consuming the new session-owned dependency
• public event API exposure
• watchers
• shared product-wide session framework beyond what this boundary needs

Non-Goals

• move packer ownership into the same session abstraction
• create a multi-project global VFS cache
• redesign the project launcher UX

Execution Method

Step 1 - Introduce a Studio Project-Session Holder for prometeu-vfs

What: Create the Studio-side owner that keeps prometeu-vfs alive for the lifetime of an opened project window.

How: Add a project-session abstraction or holder in prometeu-studio that stores:

• the ProjectReference
• the session-owned prometeu-vfs instance or facade
• shutdown/close behavior

This holder must not be tied to workspace focus.

File(s):

• new prometeu-studio/src/main/java/p/studio/projectsessions/**
• prometeu-studio/src/main/java/p/studio/Container.java

Step 2 - Wire Session Creation into the Project Open Path

What: Construct and dispose the project-session-owned prometeu-vfs at the same level where the project window lifecycle is managed.

How: Update project-open flow so StudioWindowCoordinator creates the project session before the main window is shown and closes it when the project window is torn down.

File(s):

• prometeu-studio/src/main/java/p/studio/window/StudioWindowCoordinator.java
• prometeu-app/src/main/java/p/studio/AppContainer.java

Step 3 - Pass the Session into the Main Shell

What: Make the project-session-owned prometeu-vfs available to shell consumers without making the container globally own per-project state.

How: Update MainView construction and related shell wiring so project-scoped consumers receive the session-owned dependency explicitly.

File(s):

• prometeu-studio/src/main/java/p/studio/window/MainView.java
• new prometeu-studio/src/main/java/p/studio/projectsessions/**

Step 4 - Add Session Lifecycle Tests

What: Verify that prometeu-vfs lifecycle follows project-window lifetime rather than workspace focus changes.

How: Add tests that cover:

• session creation on project open
• session reuse while switching workspaces
• session shutdown on project window close

File(s):

• new prometeu-studio/src/test/java/p/studio/projectsessions/**
• new prometeu-studio/src/test/java/p/studio/window/**

Test Requirements

Unit Tests

• session holder lifecycle behavior
• shutdown behavior

Integration Tests

• coordinator-level test for project-open and project-close lifecycle

Manual Verification

• open a project, switch between workspaces, and confirm document state is not recreated by workspace focus changes
• close the project window and confirm project-session resources are released

Acceptance Criteria

• prometeu-vfs is owned by a Studio project session rather than EditorWorkspace
• opening a project creates the session before normal editor consumption
• workspace focus changes do not destroy the project-document state
• closing the project window releases session-owned resources

Affected Artifacts

• prometeu-studio/src/main/java/p/studio/Container.java
• prometeu-app/src/main/java/p/studio/AppContainer.java
• prometeu-studio/src/main/java/p/studio/window/StudioWindowCoordinator.java
• prometeu-studio/src/main/java/p/studio/window/MainView.java
• new prometeu-studio/src/main/java/p/studio/projectsessions/**
• new prometeu-studio/src/test/java/p/studio/projectsessions/**
• new prometeu-studio/src/test/java/p/studio/window/**

Risks

• letting the container own per-project state globally would collapse window boundaries
• placing ownership too low in the shell would recreate the same focus-coupling problem under a different name
• weak disposal semantics would leak project-session resources after window close