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

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 semantic-read consumer boundary used by the integrated LSP phase,
• 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
• 5. Code Editor Workspace Specification.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 the integrated prometeu-lsp phase consumes this boundary as a semantic-read client rather than as a persistence owner.

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.

Semantic-Read Consumer Boundary

prometeu-vfs must remain the source-of-truth document substrate consumed by the integrated LSP semantic-read phase.

Rules:

• opened frontend documents must be exposed to prometeu-lsp from the in-memory editorial snapshot held by prometeu-vfs;
• unopened frontend documents may be exposed to prometeu-lsp from filesystem-backed state through the same boundary;
• prometeu-lsp must not bypass prometeu-vfs with ad hoc filesystem reads inside Studio UI code;
• prometeu-lsp must not become the owner of save, persistence, or access policy;
• semantic analysis over editorial snapshots must remain separate from build-facing document ownership;
• and this boundary must remain suitable for frontend diagnostics, symbols, definition, and highlight without implying frontend edit rights.

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 serves prometeu-lsp as a consumer-facing substrate for the semantic-read phase;
• 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 semantic-read consumer boundary with prometeu-lsp is explicit,
• the RPC-first public API rule is explicit,
• and deferred public events and watchers are clearly out of scope.