diff --git a/discussion/index.ndjson b/discussion/index.ndjson index bc5ef319..0fdb8037 100644 --- a/discussion/index.ndjson +++ b/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":[]} diff --git a/discussion/workflow/plans/PLN-0015-propagate-dec-0009-into-studio-specs.md b/discussion/workflow/plans/PLN-0015-propagate-dec-0009-into-studio-specs.md index 7076f003..b50bbfcb 100644 --- a/discussion/workflow/plans/PLN-0015-propagate-dec-0009-into-studio-specs.md +++ b/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 diff --git a/docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md b/docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md index c21a86aa..19b415c1 100644 --- a/docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md +++ b/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. diff --git a/docs/specs/studio/5. Code Editor Workspace Specification.md b/docs/specs/studio/5. Code Editor Workspace Specification.md index 2762f0b5..0c8a9134 100644 --- a/docs/specs/studio/5. Code Editor Workspace Specification.md +++ b/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 diff --git a/docs/specs/studio/6. Project Document VFS Specification.md b/docs/specs/studio/6. Project Document VFS Specification.md new file mode 100644 index 00000000..f526f5da --- /dev/null +++ b/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. diff --git a/docs/specs/studio/README.md b/docs/specs/studio/README.md index 1be82fa5..58f779f0 100644 --- a/docs/specs/studio/README.md +++ b/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.