222 lines
8.7 KiB
Markdown
222 lines
8.7 KiB
Markdown
# Project Document VFS Specification
|
|
|
|
## Status
|
|
|
|
Active
|
|
|
|
## Applies To
|
|
|
|
- `prometeu-vfs`
|
|
- `prometeu-studio`
|
|
- the Studio project-document boundary for the first controlled Code Editor write 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,
|
|
- canonical frontend scope and access policy ownership,
|
|
- editorial snapshot and save ownership for editable non-frontend documents,
|
|
- 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,
|
|
- build participation for editorial snapshots by implication,
|
|
- 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,
|
|
- the owner of document access policy for the covered scope,
|
|
- the owner of save persistence for editable documents in this wave,
|
|
- 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;
|
|
- `prometeu-vfs` must classify each supported document as at least editable or hard `read-only`;
|
|
- unsupported documents must remain distinguishable from supported `read-only` and supported editable documents;
|
|
- `prometeu-vfs` must own editable in-memory editorial snapshots for the current Studio session;
|
|
- save operations for editable documents in this wave must persist those editorial snapshots to disk through `prometeu-vfs`;
|
|
- Studio consumers must treat `prometeu-vfs` access policy as canonical rather than rederiving editability locally;
|
|
- and editorial snapshots must remain outside build-facing document state.
|
|
|
|
## Frontend Scope Contract
|
|
|
|
Frontend scope must be decided canonically inside `prometeu-vfs`.
|
|
|
|
Rules:
|
|
|
|
- `FrontendSpec.allowedExtensions` is the source of truth for frontend scope in this wave;
|
|
- the VFS document contract must expose a canonical frontend-compatible `typeId` or equivalent scope marker derived from that source of truth;
|
|
- consumers must not infer frontend scope from raw dynamic language identifiers, path heuristics, or local UI extension checks;
|
|
- frontend-scoped supported documents must remain hard `read-only` in this wave;
|
|
- the initial editable non-frontend set is limited to the currently supported textual classes represented as `text`, `json`, `ndjson`, and `bash`;
|
|
- and no additional editable class may be inferred by implementation convenience during this wave.
|
|
|
|
## Document Access Context
|
|
|
|
`prometeu-vfs` must reserve a single access-context entity for document-access-related values.
|
|
|
|
Rules:
|
|
|
|
- the access-context entity may remain session-local in this wave;
|
|
- it must already support lookup and mutation under current demand;
|
|
- future persistence may be added later without redesigning the access model;
|
|
- and the current reservation must not be treated as authorization for build participation or broader product-wide state ownership.
|
|
|
|
## 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
|
|
- dirty tracking
|
|
- merge or conflict handling
|
|
- non-project content snapshots
|
|
- a generic product-wide filesystem abstraction
|
|
- frontend editing
|
|
- treating editorial snapshots as canonical build input
|
|
|
|
## 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,
|
|
- frontend scope and access policy ownership are explicit,
|
|
- editable non-frontend snapshot and save ownership are explicit,
|
|
- the RPC-first public API rule is explicit,
|
|
- and deferred public events and watchers are clearly out of scope.
|