---
id: PLN-0017
ticket: studio-editor-document-vfs-boundary
title: Add Studio project-session ownership for `prometeu-vfs`
status: done
created: 2026-03-31
completed: 2026-03-31
tags:
  - 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