126 lines
6.4 KiB
Markdown
126 lines
6.4 KiB
Markdown
---
|
|
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.
|