Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/discussion/workflow/decisions/DEC-0011-studio-frontend-read-only-minimum-lsp-phase.md
bQUARKz 91ca49a074
editor and lsp
2026-03-31 11:12:52 +01:00

7.5 KiB
Raw Blame History

id ticket title status created accepted agenda plans tags
DEC-0011 studio-editor-write-wave-supported-non-frontend-files Establish the frontend read-only minimum LSP phase in Studio accepted 2026-03-31 2026-03-31 AGD-0014
PLN-0022
PLN-0023
PLN-0024
PLN-0025
studio
editor
workspace
frontend-boundary
lsp
access-policy

Context

The controlled non-frontend write wave intentionally kept frontend-scoped documents read-only.

After that closure, the next question was not "how to edit frontend now", but rather:

  • whether Studio could already gain semantic value over frontend documents while they remain read-only,
  • how prometeu-lsp should relate to prometeu-vfs,
  • what minimum semantic scope is worth shipping,
  • and how to keep this phase separate from the later decision that may release frontend editing.

The accepted agenda closed that this phase should remain explicitly read-only for frontend documents while introducing a minimum integrated LSP layer over the same project-session document substrate.

Decision

  1. Studio SHALL introduce a frontend read-only semantic phase before any frontend editing phase is considered.
  2. This phase SHALL keep frontend-scoped documents hard read-only.
  3. This phase SHALL introduce a minimum integrated prometeu-lsp consumer above prometeu-vfs.
  4. prometeu-lsp SHALL consume document state exposed by prometeu-vfs.
  5. For opened frontend documents, prometeu-lsp SHALL analyze the in-memory session snapshot exposed by prometeu-vfs.
  6. For unopened frontend documents, prometeu-lsp MAY fall back to filesystem-backed state exposed through the same document boundary.
  7. prometeu-lsp MUST NOT become the owner of document persistence, save policy, or access policy.
  8. prometeu-vfs SHALL remain the owner of document state, snapshots, persistence, and access-policy context.
  9. Frontend scope in this phase SHALL continue to use FrontendSpec.allowedExtensions as source of truth, and the VFS contract SHALL expose a frontend-compatible canonical typeId or equivalent scope marker derived from that source of truth.
  10. The minimum semantic scope of this phase SHALL include:
  • diagnostics,
  • document symbols and workspace symbols,
  • outline-facing structural symbol data,
  • definition,
  • highlight for frontend documents.
  1. Highlight for non-frontend documents MAY remain Studio-local as currently implemented in this phase.
  2. Highlight for frontend documents SHALL come from semantic information provided through prometeu-lsp and SHALL use frontend-owned color semantics rather than a Studio-local fallback scheme.
  3. Completion SHALL remain out of scope for this minimum read-only phase.
  4. Rename, code actions, formatting, and any frontend edit-right release SHALL remain out of scope for this phase.
  5. The future release of frontend editing SHALL be handled by a separate discussion and decision.
  6. The editorial in-memory state observed by prometeu-lsp MAY feed semantic analysis, but MUST NOT be treated as canonical build input by implication.
  7. Any future bridge between frontend editorial state and build-facing state SHALL require a separate explicit decision.
  8. prometeu-lsp API organization SHALL prefer flat packaging modeled after prometeu-packer-api, using explicit public surfaces such as dtos, messages, and events where appropriate.
  9. prometeu-vfs does not need to persist document-access context yet, but it SHALL introduce a single context entity for such values so that read, mutation, and future persistence remain a natural extension rather than a redesign.

Rationale

This decision separates semantic readiness from editing rights.

That separation is valuable because frontend files are materially different from generic textual documents. For frontend documents, even a minimum Studio-integrated semantic consumer provides immediate value:

  • diagnostics,
  • outline and symbols,
  • definition,
  • highlight,
  • and a validated path from document session state into semantic reading.

At the same time, keeping editing out of this phase protects the product from releasing mutation before its semantic consumer and editorial boundaries are ready.

The decision also preserves a clean ownership model:

  • prometeu-vfs owns document state,
  • prometeu-lsp consumes that state,
  • the editor owns UX,
  • and build remains separate.

Technical Specification

1. Phase Boundary

  • This decision defines a frontend semantic-read phase, not a frontend editing phase.
  • Frontend documents remain hard read-only throughout this decision's scope.
  • No plan derived from this decision may infer save, mutation, or frontend dirty-tracking rights.

2. Document Source of Truth for Analysis

  • Opened frontend documents MUST be analyzed from the in-memory document snapshot held by prometeu-vfs.
  • Closed frontend documents MAY be analyzed from filesystem-backed document state through the same boundary.
  • Frontend scope MUST continue to derive from FrontendSpec.allowedExtensions.
  • The VFS contract MUST expose a frontend-compatible canonical typeId or equivalent scope marker derived from that source of truth.
  • Consumers MUST NOT bypass prometeu-vfs with ad hoc file loading inside Studio UI code.

3. Minimum LSP Capability Set

  • The minimum phase MUST provide:
    • diagnostics,
    • document symbols,
    • workspace symbols,
    • outline-facing symbol structure,
    • go-to-definition,
    • frontend highlight.
  • Completion is explicitly excluded from this minimum phase.
  • Highlight for non-frontend files may remain Studio-local during this phase.
  • Highlight for frontend files MUST come from LSP semantic output and frontend-owned color semantics.

4. Ownership Rules

  • prometeu-lsp MUST remain a semantic consumer.
  • prometeu-lsp MUST NOT own:
    • save,
    • persistence,
    • document access policy,
    • frontend edit-right release.
  • prometeu-vfs MUST remain the owner of document state and access context.

5. Packaging Rules

  • The public API of prometeu-lsp SHOULD use flat packaging similar to prometeu-packer-api.
  • Public contract types SHOULD be grouped under explicit, shallow package surfaces such as:
    • dtos
    • messages
    • events
  • Deep packaging by internal implementation concern SHOULD be avoided for public contract surfaces.

6. Context Reservation

  • prometeu-vfs MUST introduce a single context entity for document-access-related values that may evolve later.
  • This context does not need persistence yet.
  • It MUST already support lookup and mutation under current demand so that future persistence can be added without reworking the model.

7. Boundary with Build

  • Semantic analysis over editorial in-memory state does not authorize build participation.
  • No implementation derived from this decision may treat editorial snapshots as canonical build inputs.
  • Build-facing transitions require separate decision work.

Constraints

  • This decision does not release frontend editing.
  • This decision does not authorize completion.
  • This decision does not authorize semantic gating of save because save for frontend files remains out of scope.
  • This decision does not authorize external-editor compatibility requirements.

Revision Log

  • 2026-03-31: Initial accepted decision from AGD-0014.
  • 2026-03-31: Clarified frontend scope source-of-truth via FrontendSpec.allowedExtensions, hardened frontend read-only semantics, and locked frontend highlight to LSP semantic output while non-frontend highlight remains Studio-local.