implements PLN-0015

discussion/index.ndjson

@@ -10,4 +10,4 @@
 {"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
 {"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
-{"type":"discussion","id":"DSC-0012","status":"open","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[{"id":"AGD-0012","file":"AGD-0012-studio-editor-document-vfs-boundary.md","status":"in_progress","created_at":"2026-03-31","updated_at":"2026-03-31"}],"decisions":[{"id":"DEC-0009","file":"DEC-0009-studio-prometeu-vfs-project-document-boundary.md","status":"in_progress","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0012"}],"plans":[{"id":"PLN-0015","file":"PLN-0015-propagate-dec-0009-into-studio-specs.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]},{"id":"PLN-0016","file":"PLN-0016-build-prometeu-vfs-filesystem-backed-core.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]},{"id":"PLN-0017","file":"PLN-0017-add-studio-project-session-ownership-for-prometeu-vfs.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]},{"id":"PLN-0018","file":"PLN-0018-migrate-code-editor-to-prometeu-vfs.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]}],"lessons":[]}
+{"type":"discussion","id":"DSC-0012","status":"open","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[{"id":"AGD-0012","file":"AGD-0012-studio-editor-document-vfs-boundary.md","status":"in_progress","created_at":"2026-03-31","updated_at":"2026-03-31"}],"decisions":[{"id":"DEC-0009","file":"DEC-0009-studio-prometeu-vfs-project-document-boundary.md","status":"in_progress","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0012"}],"plans":[{"id":"PLN-0015","file":"PLN-0015-propagate-dec-0009-into-studio-specs.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]},{"id":"PLN-0016","file":"PLN-0016-build-prometeu-vfs-filesystem-backed-core.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]},{"id":"PLN-0017","file":"PLN-0017-add-studio-project-session-ownership-for-prometeu-vfs.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]},{"id":"PLN-0018","file":"PLN-0018-migrate-code-editor-to-prometeu-vfs.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]}],"lessons":[]}

discussion/workflow/plans/PLN-0015-propagate-dec-0009-into-studio-specs.md

@@ -2,9 +2,9 @@
 id: PLN-0015
 ticket: studio-editor-document-vfs-boundary
 title: Propagate DEC-0009 into Studio shell, editor, and VFS specs
-status: review
+status: done
 created: 2026-03-31
-completed:
+completed: 2026-03-31
 tags:
   - studio
   - vfs

docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md

@@ -62,6 +62,7 @@ Baseline workspace architecture rules are:
 
 - each workspace should have a composition root that mounts the workspace into the shell;
 - a workspace composition root should coordinate workspace services, state orchestration, and structural sync, but it should not own every local render path directly;
+- project-session services that must survive workspace focus changes should be owned above individual workspace focus lifecycles and then consumed by workspace composition roots;
 - event-observing workspace controls must be lifecycle-managed;
 - workspace-local updates should flow through the Studio event system rather than ad hoc imperative redraw chains;
 - future workspaces should consume shared Studio workspace framework primitives where those primitives already cover the needed behavior.
@@ -71,6 +72,14 @@ The shell must not encourage a workspace model where every interaction falls bac
 Detailed local workspace composition remains workspace-owned.
 For example, `Code Editor`-local layout, navigator behavior, tab rules, passive placeholder surfaces, and read-only file behavior are not shell-global rules and must be defined by the workspace-local editor specification.
 
+Project-session boundaries may still exist above a workspace when the state must remain alive while the project window stays open.
+
+Rules:
+
+- the shell may construct and own project-session services that survive workspace focus changes;
+- workspaces may consume those project-session services without inheriting their ownership;
+- introducing a project-session service must not collapse shell and workspace responsibilities into one monolithic root.
+
 ## Right Utility Panel
 
 The right-side global utility surface is tab-based.

docs/specs/studio/5. Code Editor Workspace Specification.md

@@ -30,6 +30,7 @@ This specification extends:
 - [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
 - [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md)
 - [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md)
+- [`6. Project Document VFS Specification.md`](6.%20Project%20Document%20VFS%20Specification.md)
 
 If this document conflicts with the global Studio shell specifications, the shell specifications control shell-wide behavior and this document controls workspace-local editor behavior.
 
@@ -45,6 +46,7 @@ The `Code Editor` workspace must assume:
 - and the current wave must not depend on write/save or semantic behavior to remain coherent.
 
 This workspace may consume Studio project metadata and Studio-owned workspace framework primitives, but it must not infer a semantic-provider contract beyond keeping the path open for later integration.
+This workspace must consume project tree and document data through `prometeu-vfs` rather than through editor-owned direct filesystem readers.
 
 ## Workspace Model
 
@@ -99,6 +101,7 @@ The `Code Editor` workspace must be implemented as a composition root plus child
 Rules:
 
 - the workspace root should coordinate layout, workspace-level session state, and structural synchronization;
+- the workspace root should consume project-session-owned document services such as `prometeu-vfs` rather than owning their lifecycle locally;
 - the `Project Navigator`, tab strip, editor body, reserved `Outline`, helper region, and status bar should exist as explicit local surfaces;
 - passive placeholder surfaces must remain visually real without implying unsupported functionality;
 - and the first wave should preserve a clean path for later extraction of reusable Studio controls when the surfaces become stable enough to justify that move.
@@ -113,9 +116,10 @@ Rules:
 
 ### Structural Snapshot
 
-- The navigator must maintain an in-memory structural snapshot of the project tree for navigation and visual state.
-- That structural snapshot must not replace the filesystem as the source of truth.
-- Content snapshots are separate and are only required for files that are actually opened in the editor.
+- The navigator must consume a structural project-tree entity provided by `prometeu-vfs`.
+- That structural tree must not replace the filesystem as the source of truth.
+- Content snapshots are separate and are only required for files that are actually opened in the editor through `prometeu-vfs`.
+- The navigator may request more targeted tree refresh operations than a full-tree reload when the `prometeu-vfs` contract provides them.
 
 ### Visibility and Ordering
 
@@ -129,22 +133,25 @@ Rules:
 - `prometeu.json` plus the selected frontend may be used to tag relevant source roots or source directories.
 - That tagging must not hide non-source project files.
 - That tagging must not imply semantic/editor-language ownership by the navigator itself.
+- Rendering those tags remains a Studio UI concern even when the source data comes from `prometeu-vfs`.
 
 ### Refresh Model
 
 - The navigator must perform one initial refresh when the project opens.
-- The navigator must expose a manual refresh action directly on the navigator surface.
+- The navigator must expose a manual refresh action directly on the navigator surface and route that request through `prometeu-vfs`.
 - Watcher-driven automatic refresh is explicitly deferred from this wave.
 
 ### Unsupported Files
 
 - Unsupported or non-text files may still appear in the navigator.
+- File support and unsupported-file classification belong to `prometeu-vfs`.
 - Attempting to open such a file must show a simple modal stating that the file is not supported in this wave.
 - The workspace must not fake a partial preview to imply unsupported file-format coverage.
 
 ## Tabs and File Opening Rules
 
 - Selecting a supported file that is not already open must open it in a new tab.
+- File opening must resolve document content through `prometeu-vfs`.
 - The editor must maintain opened-file content in memory for the active Studio session only.
 - The tab strip must be responsive rather than fixed to one hardcoded tab count.
 - Overflow tabs must remain accessible through an IntelliJ-style overflow control.
@@ -215,6 +222,13 @@ That includes at minimum:
 - tree expansion state,
 - and similar visual editor state.
 
+The following remain outside editor-owned session state:
+
+- project-session ownership of `prometeu-vfs`,
+- structural project-tree data returned by `prometeu-vfs`,
+- support classification rules,
+- and document loading responsibilities.
+
 Persisting that state across Studio executions is deferred.
 
 ## Non-Goals
@@ -223,6 +237,7 @@ Persisting that state across Studio executions is deferred.
 - dirty tracking
 - merge/conflict resolution
 - watcher-driven automatic refresh
+- public `prometeu-vfs` event APIs
 - active outline behavior
 - helper panel functionality
 - semantic analysis surfaces

docs/specs/studio/6. Project Document VFS Specification.md

@@ -0,0 +1,186 @@
+# Project Document VFS Specification
+
+## Status
+
+Active
+
+## Applies To
+
+- `prometeu-vfs`
+- `prometeu-studio`
+- the Studio project-document boundary for the first Code Editor migration wave
+
+## Purpose
+
+Define the normative Studio contract for `prometeu-vfs` as the project-document boundary consumed by Studio workspaces.
+
+This specification stabilizes:
+
+- `prometeu-vfs` module role,
+- project-session ownership,
+- the filesystem-backed first-wave contract,
+- structural tree and document access responsibilities,
+- the RPC-first public API baseline,
+- and explicit first-wave exclusions such as public event publication and watchers.
+
+## Authority and Precedence
+
+This specification extends:
+
+- [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
+- [`5. Code Editor Workspace Specification.md`](5.%20Code%20Editor%20Workspace%20Specification.md)
+
+If this document conflicts with shell-wide Studio rules, the shell specification controls shell-wide behavior and this document controls the project-document boundary contract.
+
+## Normative Inputs
+
+`prometeu-vfs` must assume:
+
+- the current migration wave carries only the Code Editor capabilities that already exist today,
+- the initial backend is filesystem-backed,
+- the boundary is project-scoped rather than product-global,
+- the boundary must outlive workspace focus changes for an opened project,
+- Studio UI remains the owner of visual tree state and error presentation,
+- and future consumers such as `prometeu-lsp` may depend on this boundary later.
+
+`prometeu-vfs` must not infer:
+
+- watcher-driven refresh in this wave,
+- public event API exposure in this wave,
+- write or save semantics,
+- or ownership over non-Studio domains such as packer assets.
+
+## Module Role
+
+`prometeu-vfs` is:
+
+- the Studio project-document boundary,
+- the owner of project structural tree data for the covered scope,
+- the owner of project document resolution for the covered scope,
+- the owner of file support and unsupported-file classification for the covered scope,
+- and the required path through which Studio accesses project-document filesystem state in this wave.
+
+`prometeu-vfs` is not:
+
+- a visual tree control,
+- a Studio shell replacement,
+- a product-wide universal filesystem layer,
+- or a public event transport in this wave.
+
+## Project Session Ownership
+
+The primary `prometeu-vfs` instance must belong to the Studio project session.
+
+Rules:
+
+- a project-scoped `prometeu-vfs` instance must be created when a Studio project session is opened;
+- that instance must remain alive while the project session remains open;
+- switching workspace focus must not destroy or recreate the project-document state by default;
+- the `Code Editor` workspace must consume the session-owned `prometeu-vfs` instance rather than owning the boundary lifecycle itself;
+- the project-session scope must cover only the opened project.
+
+## Filesystem Access Rules
+
+For the scope covered by this specification, Studio must access the project filesystem through `prometeu-vfs`.
+
+Rules:
+
+- the first implementation must be filesystem-backed;
+- direct filesystem reads for project tree and document loading must not remain a workspace-owned responsibility in the Code Editor;
+- this rule does not grant `prometeu-vfs` ownership over unrelated domains or unrelated filesystem responsibilities elsewhere in the product.
+
+## Structural Tree Contract
+
+`prometeu-vfs` must expose a structural representation of the project tree.
+
+Rules:
+
+- the structural tree must cover project content only;
+- the structural tree must contain structural and documentary data only;
+- the structural tree must not contain visual presentation state;
+- the structural tree must not contain navigator chrome decisions;
+- the structural tree may include structural metadata useful to Studio consumers;
+- consumers may request narrower refreshes than a full-tree reload when the request remains within the project boundary.
+
+The following concerns remain outside `prometeu-vfs`:
+
+- visual expansion state,
+- selection state,
+- focus state,
+- reveal or scroll behavior,
+- icon choice,
+- and other view-model concerns of the navigator UI.
+
+## Document Access Contract
+
+`prometeu-vfs` must own document resolution for the covered Studio scope.
+
+Rules:
+
+- opening a supported file in the Code Editor must go through `prometeu-vfs`;
+- the returned document content must describe only project-session document state for the opened project;
+- this wave must not add save, dirty tracking, merge, or conflict semantics by implication;
+- future in-memory overlays may be added only by later explicit decision.
+
+## Support and Plugin Rules
+
+Support and unsupported-file decisions belong to `prometeu-vfs`.
+
+Rules:
+
+- file support classification must be decided inside `prometeu-vfs`;
+- plugin or handler resolution for supported file access must be decided inside `prometeu-vfs`;
+- Studio UI may render the resulting success or failure state, but it must not own the classification rule itself.
+
+## Communication Model
+
+The official first-wave `prometeu-vfs` API is RPC-oriented.
+
+Rules:
+
+- commands and queries are the public API baseline for this wave;
+- internal runtime events may exist inside `prometeu-vfs`;
+- those events must remain internal in this wave;
+- internal events must not be promoted to public API by inference during planning or implementation.
+
+## Refresh and Watchers
+
+Refresh remains manual in this wave.
+
+Rules:
+
+- Studio consumers may request manual refresh through `prometeu-vfs`;
+- watcher-driven automatic refresh is deferred;
+- file watching must not be introduced implicitly while implementing this specification.
+
+## Cross-Domain Boundary
+
+`prometeu-vfs` belongs to the Studio domain.
+
+Rules:
+
+- `prometeu-vfs` may later serve `prometeu-lsp` as a consumer-facing substrate;
+- `prometeu-lsp` remains a separate layer and must not be renamed into `prometeu-vfs`;
+- `prometeu-vfs` must not absorb packer responsibilities;
+- `prometeu-vfs` must not redefine asset ownership;
+- extending this boundary outside project-document concerns requires a new decision.
+
+## Non-Goals
+
+- public event publication
+- watcher-driven refresh
+- write or save behavior
+- dirty tracking
+- merge or conflict handling
+- non-project content snapshots
+- a generic product-wide filesystem abstraction
+
+## Exit Criteria
+
+This specification is complete enough when:
+
+- `prometeu-vfs` ownership is clearly separated from shell and workspace UI ownership,
+- the project-session lifecycle rule is unambiguous,
+- the structural tree contract is explicitly non-visual,
+- the RPC-first public API rule is explicit,
+- and deferred public events and watchers are clearly out of scope.

docs/specs/studio/README.md

@@ -55,6 +55,7 @@ The current Studio core corpus is:
 3. [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md)
 4. [`4. Assets Workspace Specification.md`](4.%20Assets%20Workspace%20Specification.md)
 5. [`5. Code Editor Workspace Specification.md`](5.%20Code%20Editor%20Workspace%20Specification.md)
+6. [`6. Project Document VFS Specification.md`](6.%20Project%20Document%20VFS%20Specification.md)
 
 ## Reading Order
 
@@ -63,5 +64,6 @@ Recommended order:
 1. shell and workspace layout;
 2. shared UI foundations;
 3. components module policy;
-4. assets workspace behavior;
-5. code editor workspace behavior.
+4. project document VFS boundary;
+5. assets workspace behavior;
+6. code editor workspace behavior.