Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/discussion/workflow/decisions/DEC-0010-studio-controlled-non-frontend-editor-write-wave.md
bQUARKz 91ca49a074
editor and lsp
2026-03-31 11:12:52 +01:00

7.3 KiB
Raw Blame History

id ticket title status created accepted agenda plans tags
DEC-0010 studio-editor-write-wave-supported-non-frontend-files Establish the controlled non-frontend editor write wave in Studio accepted 2026-03-31 2026-03-31 AGD-0013
PLN-0019
PLN-0020
PLN-0021
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.