137 lines
7.3 KiB
Markdown
137 lines
7.3 KiB
Markdown
---
|
|
id: DEC-0010
|
|
ticket: studio-editor-write-wave-supported-non-frontend-files
|
|
title: Establish the controlled non-frontend editor write wave in Studio
|
|
status: accepted
|
|
created: 2026-03-31
|
|
accepted: 2026-03-31
|
|
agenda: AGD-0013
|
|
plans:
|
|
- PLN-0019
|
|
- PLN-0020
|
|
- PLN-0021
|
|
tags:
|
|
- studio
|
|
- editor
|
|
- workspace
|
|
- write
|
|
- read-only
|
|
- vfs
|
|
- frontend-boundary
|
|
---
|
|
|
|
## Context
|
|
|
|
The first Studio `Code Editor` wave established a read-only editorial shell and later moved project-document ownership into `prometeu-vfs`.
|
|
|
|
That left one immediate follow-up decision:
|
|
|
|
- which files may become editable now,
|
|
- which files must remain `read-only`,
|
|
- where access policy lives,
|
|
- how save works,
|
|
- and how editorial in-memory state stays contained away from build-facing state.
|
|
|
|
The accepted agenda closed the intended first write wave as deliberately narrower than "all supported text files":
|
|
|
|
- the same supported-document universe remains valid for opening,
|
|
- but access policy must distinguish `read-only` from `editable`,
|
|
- frontend-scoped files remain `read-only`,
|
|
- and only already-supported non-frontend text classes enter the first write wave.
|
|
|
|
## Decision
|
|
|
|
1. Studio SHALL introduce a controlled first editor write wave only for supported non-frontend documents.
|
|
2. The canonical document universe for this wave SHALL remain the same universe already supported for opening through `prometeu-vfs`.
|
|
3. `prometeu-vfs` SHALL own document access policy for this wave, including `load`, `save`, and the classification of each supported document as `read-only` or `editable`.
|
|
4. `EditorWorkspace` MUST consume access policy from `prometeu-vfs` and MUST NOT rederive editability rules locally.
|
|
5. Frontend-scoped documents SHALL remain hard `read-only` in this wave.
|
|
6. Frontend scope SHALL be decided inside `prometeu-vfs` using `FrontendSpec.allowedExtensions` as the source of truth.
|
|
7. The `prometeu-vfs` contract SHALL evolve so that `typeId` canonically represents that frontend scope in a way compatible with `FrontendSpec.allowedExtensions`, rather than exposing only a raw dynamic language identifier.
|
|
8. The initial editable non-frontend document classes SHALL be limited to the currently supported textual classes represented as `text`, `json`, `ndjson`, and `bash`.
|
|
9. No additional document-support class SHALL be inferred or added by implementation convenience during this wave.
|
|
10. For editable documents in this wave, `prometeu-vfs` SHALL maintain an in-memory editorial snapshot for the current Studio session.
|
|
11. `save` SHALL persist that in-memory editorial snapshot to disk through `prometeu-vfs`.
|
|
12. The global shell `Save` menu item MUST NOT be the save surface for this wave.
|
|
13. Save actions for this wave SHALL live inside the editor itself through a top command bar containing at least `Save` and `Save All`.
|
|
14. Frontend-scoped hard `read-only` tabs MAY coexist with editable non-frontend tabs in the same editor workspace.
|
|
15. Frontend-scoped hard `read-only` documents SHALL expose a `read-only` state in the editor status bar.
|
|
16. The status-bar `read-only` surface SHOULD be designed so that it can evolve later into a per-file toggle without requiring a model rewrite.
|
|
17. Frontend-scoped hard `read-only` documents MUST NOT allow local editorial mutation in this wave.
|
|
18. Opening a frontend-scoped hard `read-only` document SHALL also show a top-of-editor warning stating that the file is `read-only`, cannot be edited, and cannot be saved in this wave.
|
|
19. The editable documents in this wave SHALL be treated as editorial scope and SHALL NOT participate in the build by implication.
|
|
20. The in-memory editorial snapshot used for this wave MUST remain contained and MUST NOT be treated as canonical build input.
|
|
21. No implementation in this wave MAY collapse editorial session snapshots into build-facing or artifact-facing document state by inference.
|
|
|
|
## Rationale
|
|
|
|
This decision preserves the correct architectural order.
|
|
|
|
The editor needed real write behavior, but not at the cost of undoing the `prometeu-vfs` boundary that was just established.
|
|
Keeping access policy in `prometeu-vfs` prevents a return to editor-local conditional logic.
|
|
|
|
Keeping frontend documents `read-only` avoids releasing mutation for language-owned files before semantic support is ready.
|
|
At the same time, allowing already-supported non-frontend text classes to become editable gives the Studio a meaningful write wave without pretending that all textual files belong to the same product tier.
|
|
|
|
The decision also protects the build boundary.
|
|
Having an in-memory editorial snapshot is necessary for writing, but it must not silently become the source of truth for build consumers.
|
|
|
|
## Technical Specification
|
|
|
|
### 1. Access Policy Surface
|
|
|
|
- `prometeu-vfs` MUST expose access policy as part of the document contract for supported files.
|
|
- That policy MUST distinguish at least:
|
|
- unsupported document,
|
|
- supported `read-only` document,
|
|
- supported editable document.
|
|
- The editor MUST treat this classification as canonical.
|
|
|
|
### 2. Frontend Classification
|
|
|
|
- `prometeu-vfs` MUST classify frontend scope internally.
|
|
- `FrontendSpec.allowedExtensions` MUST be the source of truth for that classification.
|
|
- The VFS contract MUST expose a frontend-compatible canonical `typeId` or equivalent scope marker derived from that source of truth.
|
|
- The editor MUST NOT infer frontend scope from path heuristics, local UI state, or ad hoc extension checks.
|
|
|
|
### 3. Editable Non-Frontend Set
|
|
|
|
- Editable scope in this wave is limited to the currently supported textual document classes:
|
|
- `text`
|
|
- `json`
|
|
- `ndjson`
|
|
- `bash`
|
|
- Future additions require explicit decision revision or a new decision.
|
|
|
|
### 4. Editorial Snapshot and Save
|
|
|
|
- Editable documents MUST have a session-owned in-memory editorial snapshot.
|
|
- `prometeu-vfs` MUST own the mutation-ready document state that `Save` and `Save All` use.
|
|
- Persisting to disk MUST happen through `prometeu-vfs`.
|
|
- The editor MUST remain a caller of save intent, not the owner of persistence policy.
|
|
|
|
### 5. UI Surfaces
|
|
|
|
- The editor MUST provide a top command bar with at least `Save` and `Save All`.
|
|
- Frontend hard `read-only` state MUST be visible in the status bar.
|
|
- A frontend hard `read-only` document MUST show a top warning that it cannot be edited or saved in this wave.
|
|
- Mixed tabs between editable and `read-only` documents are allowed.
|
|
|
|
### 6. Boundary with Build
|
|
|
|
- Editorial snapshots for this wave MUST remain separate from build-facing state.
|
|
- This wave MUST NOT introduce recompilation, artifact invalidation, build triggers, or any implied build participation.
|
|
- Any future bridge between editorial state and build-facing state requires a separate explicit decision.
|
|
|
|
## Constraints
|
|
|
|
- This decision does not release frontend editing.
|
|
- This decision does not authorize completion, semantic gating, or LSP-owned save policy.
|
|
- This decision does not authorize build-side observation of editorial in-memory snapshots.
|
|
- Any ambiguity found later in planning or implementation MUST be resolved by a new explicit clarification instead of local inference.
|
|
|
|
## Revision Log
|
|
|
|
- 2026-03-31: Initial accepted decision from AGD-0013.
|
|
- 2026-03-31: Clarified that `FrontendSpec.allowedExtensions` is the source of truth for frontend scope, that VFS `typeId` must represent that scope canonically, and that frontend documents are hard read-only in this wave.
|