# 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.