Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity

clean up

Browse Source
This commit is contained in:
bQUARKz 2026-04-02 17:15:55 +01:00
parent 7bdc63a25e
commit 275a7aa408
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
21 changed files with 281 additions and 2275 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
discussion/.backups/index.ndjson.20260327-161618.bak → discussion/.backups/index.ndjson.20260402-170740.bak
View File

@ -1,9 +1,15 @@
{"type":"meta","next_id":{"DSC":9,"AGD":9,"DEC":5,"PLN":5,"LSN":23,"CLSN":1}}
{"type":"meta","next_id":{"DSC":14,"AGD":15,"DEC":13,"PLN":29,"LSN":28,"CLSN":1}}
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[{"id":"AGD-0006","file":"AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0008","status":"open","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[{"id":"AGD-0008","file":"AGD-0008-pbs-low-level-asset-manager-surface.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[{"id":"DEC-0004","file":"DEC-0004-pbs-low-level-asset-manager-surface.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27","ref_agenda":"AGD-0008"}],"plans":[{"id":"PLN-0004","file":"PLN-0004-pbs-low-level-asset-manager-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27","ref_decisions":["DEC-0004"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
{"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
{"type":"discussion","id":"DSC-0013","status":"open","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[{"id":"AGD-0013","file":"AGD-0013-studio-editor-write-wave-supported-non-frontend-files.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31"},{"id":"AGD-0014","file":"AGD-0014-studio-editor-frontend-edit-rights.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31"}],"decisions":[{"id":"DEC-0010","file":"DEC-0010-studio-controlled-non-frontend-editor-write-wave.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0013"},{"id":"DEC-0011","file":"DEC-0011-studio-frontend-read-only-minimum-lsp-phase.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0014"}],"plans":[{"id":"PLN-0019","file":"PLN-0019-propagate-dec-0010-into-studio-and-vfs-specs.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0020","file":"PLN-0020-build-dec-0010-vfs-access-policy-and-save-core.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0021","file":"PLN-0021-integrate-dec-0010-editor-write-ui-and-workflow.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0022","file":"PLN-0022-propagate-dec-0011-into-studio-vfs-and-lsp-specs.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0023","file":"PLN-0023-scaffold-flat-packed-prometeu-lsp-api-and-session-seams.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0024","file":"PLN-0024-implement-read-only-fe-diagnostics-symbols-and-definition.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0025","file":"PLN-0025-implement-fe-semantic-highlight-consumption.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0014","status":"open","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[{"id":"AGD-0015","file":"AGD-0015-studio-frontend-owned-semantic-editor-presentation.md","status":"accepted","created_at":"2026-04-02","updated_at":"2026-04-02"}],"decisions":[{"id":"DEC-0012","file":"DEC-0012-frontend-owned-semantic-editor-presentation.md","status":"accepted","created_at":"2026-04-02","updated_at":"2026-04-02","ref_agenda":"AGD-0015"}],"plans":[{"id":"PLN-0026","file":"PLN-0026-propagate-dec-0012-into-studio-and-frontend-specs.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]},{"id":"PLN-0027","file":"PLN-0027-add-frontend-semantic-presentation-contract-and-lsp-descriptor.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]},{"id":"PLN-0028","file":"PLN-0028-consume-frontend-owned-semantic-presentation-in-studio.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]}],"lessons":[]}

10
discussion/.backups/index.ndjson.20260327-165050.bak → discussion/.backups/index.ndjson.20260402-171350.bak
View File

@ -1,9 +1,15 @@
{"type":"meta","next_id":{"DSC":9,"AGD":9,"DEC":5,"PLN":5,"LSN":24,"CLSN":1}}
{"type":"meta","next_id":{"DSC":15,"AGD":16,"DEC":13,"PLN":29,"LSN":29,"CLSN":1}}
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[{"id":"AGD-0006","file":"AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
{"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-04-02","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0013-studio-editor-write-wave-supported-non-frontend-files/LSN-0028-controlled-editor-write-wave-and-read-only-frontend-semantic-phase.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
{"type":"discussion","id":"DSC-0014","status":"open","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[{"id":"AGD-0015","file":"AGD-0015-studio-frontend-owned-semantic-editor-presentation.md","status":"accepted","created_at":"2026-04-02","updated_at":"2026-04-02"}],"decisions":[{"id":"DEC-0012","file":"DEC-0012-frontend-owned-semantic-editor-presentation.md","status":"accepted","created_at":"2026-04-02","updated_at":"2026-04-02","ref_agenda":"AGD-0015"}],"plans":[{"id":"PLN-0026","file":"PLN-0026-propagate-dec-0012-into-studio-and-frontend-specs.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]},{"id":"PLN-0027","file":"PLN-0027-add-frontend-semantic-presentation-contract-and-lsp-descriptor.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]},{"id":"PLN-0028","file":"PLN-0028-consume-frontend-owned-semantic-presentation-in-studio.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]}],"lessons":[]}

6
discussion/index.ndjson
View File

@ -1,4 +1,4 @@
{"type":"meta","next_id":{"DSC":14,"AGD":15,"DEC":13,"PLN":29,"LSN":28,"CLSN":1}}
{"type":"meta","next_id":{"DSC":15,"AGD":16,"DEC":13,"PLN":29,"LSN":30,"CLSN":1}}
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
@ -11,5 +11,5 @@
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
{"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
{"type":"discussion","id":"DSC-0013","status":"open","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[{"id":"AGD-0013","file":"AGD-0013-studio-editor-write-wave-supported-non-frontend-files.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31"},{"id":"AGD-0014","file":"AGD-0014-studio-editor-frontend-edit-rights.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31"}],"decisions":[{"id":"DEC-0010","file":"DEC-0010-studio-controlled-non-frontend-editor-write-wave.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0013"},{"id":"DEC-0011","file":"DEC-0011-studio-frontend-read-only-minimum-lsp-phase.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0014"}],"plans":[{"id":"PLN-0019","file":"PLN-0019-propagate-dec-0010-into-studio-and-vfs-specs.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0020","file":"PLN-0020-build-dec-0010-vfs-access-policy-and-save-core.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0021","file":"PLN-0021-integrate-dec-0010-editor-write-ui-and-workflow.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0022","file":"PLN-0022-propagate-dec-0011-into-studio-vfs-and-lsp-specs.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0023","file":"PLN-0023-scaffold-flat-packed-prometeu-lsp-api-and-session-seams.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0024","file":"PLN-0024-implement-read-only-fe-diagnostics-symbols-and-definition.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0025","file":"PLN-0025-implement-fe-semantic-highlight-consumption.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0014","status":"open","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[{"id":"AGD-0015","file":"AGD-0015-studio-frontend-owned-semantic-editor-presentation.md","status":"accepted","created_at":"2026-04-02","updated_at":"2026-04-02"}],"decisions":[{"id":"DEC-0012","file":"DEC-0012-frontend-owned-semantic-editor-presentation.md","status":"accepted","created_at":"2026-04-02","updated_at":"2026-04-02","ref_agenda":"AGD-0015"}],"plans":[{"id":"PLN-0026","file":"PLN-0026-propagate-dec-0012-into-studio-and-frontend-specs.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]},{"id":"PLN-0027","file":"PLN-0027-add-frontend-semantic-presentation-contract-and-lsp-descriptor.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]},{"id":"PLN-0028","file":"PLN-0028-consume-frontend-owned-semantic-presentation-in-studio.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-04-02","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0013-studio-editor-write-wave-supported-non-frontend-files/LSN-0028-controlled-editor-write-wave-and-read-only-frontend-semantic-phase.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
{"type":"discussion","id":"DSC-0014","status":"done","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}

134
discussion/lessons/DSC-0013-studio-editor-write-wave-supported-non-frontend-files/LSN-0028-controlled-editor-write-wave-and-read-only-frontend-semantic-phase.md Normal file
View File

@ -0,0 +1,134 @@
---
id: LSN-0028
ticket: studio-editor-write-wave-supported-non-frontend-files
title: Controlled Editor Write Wave and Read-Only Frontend Semantic Phase
created: 2026-04-02
tags: [studio, editor, vfs, lsp, access-policy, save, read-only, frontend-boundary]
---
## Context
The first Studio `Code Editor` implementation had already established a session-owned document boundary through `prometeu-vfs`, but it was still missing the next operational split:
- which supported files could become editable now,
- which files had to remain hard `read-only`,
- where save ownership lived,
- and how frontend semantic value could ship before frontend editing rights.
This discussion closed that split in two coordinated decisions.
The result is a deliberately mixed editor phase:
- supported non-frontend textual documents can be edited and saved,
- frontend-scoped documents stay hard `read-only`,
- and frontend semantic features arrive through `prometeu-lsp` as a consumer of VFS snapshots rather than as a new document owner.
## Key Decisions
### Keep Access Policy and Save Ownership in `prometeu-vfs`
**What:**
`prometeu-vfs` is the canonical owner of document access mode, canonical `typeId`, editable in-memory snapshots, save, and save-all behavior for the first write wave.
**Why:**
The editor workspace needs to consume policy, not recreate it.
If editability, frontend classification, or save rules drift into Studio UI code, the product loses the project-document boundary that earlier work had just established.
**Trade-offs:**
This adds explicit VFS contract surface for access context, document mutation, and save orchestration.
That extra structure is intentional because it prevents editor-local heuristics from becoming product behavior.
### Release a Narrow Write Wave Instead of Universal Editing
**What:**
The editable set is intentionally limited to already-supported non-frontend textual classes: `text`, `json`, `ndjson`, and `bash`.
Frontend-scoped files stay hard `read-only` in the same workspace.
**Why:**
Not every supported text file belongs to the same product tier.
Frontend files carry language-owned semantics and future editing constraints that were not ready to ship in the same wave as generic project documents.
**Trade-offs:**
The editor becomes mixed-mode immediately, which requires clearer UX for save enablement, status-bar access state, and frontend warnings.
That is preferable to pretending all supported documents can be treated uniformly.
### Introduce Frontend Semantic Read Before Frontend Edit Rights
**What:**
`prometeu-lsp` was introduced as a semantic consumer above `prometeu-vfs` for frontend diagnostics, symbols, outline structure, definition, and semantic highlight while frontend files remain hard `read-only`.
**Why:**
Semantic readiness and editing rights should not be released together by default.
The semantic-read phase provides real value for frontend files without collapsing access policy, persistence, and semantic analysis into a single owner.
**Trade-offs:**
The system now has one more module boundary and one more contract seam to maintain.
That cost is lower than releasing frontend mutation before the semantic substrate and ownership boundaries are stable.
## Final Implementation
The final implementation landed across specs, VFS, LSP, and Studio UI:
- `docs/specs/studio/5. Code Editor Workspace Specification.md` now defines the mixed editable and hard `read-only` editor wave, editor-local `Save` and `Save All`, frontend warning surfaces, and the frontend semantic-read phase.
- `docs/specs/studio/6. Project Document VFS Specification.md` now makes `FrontendSpec.allowedExtensions` the source of truth for frontend scope, defines canonical `typeId` and access-mode ownership, and keeps editorial snapshots separate from build-facing state.
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md` now defines the minimum frontend semantic-read phase and the flat public packaging expectations for `prometeu-lsp`.
- `FilesystemVfsProjectDocument` classifies supported documents as editable or hard `read-only`, keeps editable in-memory snapshots, rejects mutation for hard `read-only` frontend documents, and persists editable snapshots through save operations.
- `prometeu-lsp` now exposes a concrete semantic-read service layer for diagnostics, symbols, definition, and frontend highlight consumption over VFS-backed session state.
- `EditorWorkspace`, `EditorOpenFileSession`, `EditorStatusBar`, and related UI surfaces now consume VFS access policy, expose editor-local save actions, and render mixed editable and frontend `read-only` tabs coherently.
## Patterns and Algorithms
### Pattern: Make the Editor a Policy Consumer
The correct ownership split is:
- `prometeu-vfs` decides supported document classification, access mode, snapshot ownership, and save behavior;
- `prometeu-lsp` consumes VFS-backed document state for semantic analysis;
- Studio UI consumes both boundaries for presentation and interaction.
This keeps each layer honest about its owner role.
### Pattern: Ship Semantic Value Before Edit Rights
When language-owned files need semantic support before mutation support, introduce a semantic-read phase instead of unlocking editing prematurely.
That pattern gives diagnostics, navigation, and semantic presentation without forcing save, dirty tracking, or mutation policy into a half-ready frontend phase.
### Example: Mixed-Mode Editor Flow
The resulting flow is:
1. `prometeu-vfs` opens a supported document and returns canonical `typeId` plus access context.
2. Studio opens the tab and renders editable or hard `read-only` state from that policy.
3. Editable non-frontend documents mutate session-owned snapshots and save through editor-local actions.
4. Frontend documents remain non-mutable, show explicit warning and status surfaces, and may still receive semantic diagnostics, symbols, definition, and highlight through `prometeu-lsp`.
## Pitfalls
- Do not let Studio UI re-derive frontend scope from file extensions or path heuristics; `FrontendSpec.allowedExtensions` must stay behind the VFS boundary.
- Do not treat editorial in-memory snapshots as canonical build input just because LSP can analyze them.
- Do not let `prometeu-lsp` absorb save, persistence, or access-policy ownership.
- Do not silently expand editable scope beyond `text`, `json`, `ndjson`, and `bash` without a new explicit decision.
- Do not release frontend editing just because frontend semantic highlight and definition already exist.
## References
- `DEC-0010` Establish the controlled non-frontend editor write wave in Studio
- `DEC-0011` Establish the frontend read-only minimum LSP phase in Studio
- `PLN-0019` Propagate DEC-0010 into Studio editor and VFS specs
- `PLN-0020` Build DEC-0010 VFS access policy and save core
- `PLN-0021` Integrate DEC-0010 editor write UI and workflow in Studio
- `PLN-0022` Propagate DEC-0011 into Studio, VFS, and LSP specs
- `PLN-0023` Scaffold flat-packed prometeu-lsp API and Studio session seams
- `PLN-0024` Implement read-only FE diagnostics, symbols, and definition over VFS snapshots
- `PLN-0025` Implement FE semantic highlight and editor consumption for the read-only LSP phase
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `docs/specs/studio/6. Project Document VFS Specification.md`
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
- `prometeu-vfs/prometeu-vfs-v1/src/main/java/p/studio/vfs/FilesystemVfsProjectDocument.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspServiceImpl.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
## Takeaways
- A mixed editable plus hard `read-only` editor wave is viable when access policy stays centralized in VFS.
- Semantic-read support is a separate product phase from frontend edit rights and should be modeled that way.
- Save ownership, semantic consumption, and UI presentation stay cleaner when `prometeu-vfs`, `prometeu-lsp`, and Studio each keep a narrow role.

127
discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md Normal file
View File

@ -0,0 +1,127 @@
---
id: LSN-0029
ticket: studio-frontend-owned-semantic-editor-presentation
title: Frontend-Owned Semantic Presentation Descriptor and Host Consumption
created: 2026-04-02
tags: [studio, editor, frontend, semantic-highlighting, lsp, compiler, pbs, presentation]
---
## Context
The first semantic highlight wave for frontend documents had already proved that Studio could consume semantic spans through the integrated LSP path.
The remaining ownership problem was narrower but important:
- semantic colors for frontend documents were still effectively hosted by Studio,
- the frontend did not publish a first-class semantic presentation contract,
- and the semantic bridge risked collapsing frontend meaning into host-owned categories.
This discussion closed that gap by moving semantic presentation ownership fully to the frontend while keeping Studio and LSP in narrow host roles.
## Key Decisions
### Make `FrontendSpec` the Canonical Semantic Presentation Contract
**What:**
The canonical semantic presentation contract now lives in `FrontendSpec` and carries frontend-owned `semanticKeys` plus frontend-owned `resources` in a single descriptor shape.
**Why:**
Semantic presentation is part of the frontend's meaning, not just an editor skin.
Keeping the contract in `FrontendSpec` lets semantic vocabulary and presentation resources evolve with the frontend itself.
**Trade-offs:**
Frontend metadata becomes slightly richer and must now be kept coherent with shipped resources.
That extra discipline is worth it because it keeps ownership explicit and versionable.
### Keep LSP as a Contract Bridge, Not a Semantic Owner
**What:**
LSP derives a semantic presentation descriptor from the resolved `FrontendSpec` and exposes it to Studio, but it does not own resources and does not translate frontend semantics into host-owned generic buckets.
**Why:**
The LSP layer should bridge analysis products into host consumption, not normalize language identity away.
If LSP emitted categories such as `fe-keyword`, it would pull frontend semantics into the wrong layer.
**Trade-offs:**
DTOs and semantic indexing need to preserve language-owned keys all the way through transport.
That is a better cost than growing a fake shared semantic vocabulary in the host stack.
### Keep Studio Mechanical and Fallback-Free
**What:**
Studio now projects frontend semantic keys mechanically into CSS classes and consumes frontend-owned resources through the descriptor.
If descriptor data or usable resources are absent, Studio simply skips semantic highlight for that frontend document.
**Why:**
Studio owns rendering plumbing and editor UX, not frontend semantics.
Mechanical projection preserves that boundary, and no generic fallback theme avoids silently reintroducing host ownership.
**Trade-offs:**
The host no longer guarantees a semantic color scheme for misconfigured frontend contracts.
That is intentional, because degraded no-highlight behavior is safer than a misleading generic fallback.
## Final Implementation
The final implementation landed across specs, compiler/frontend metadata, LSP transport, and Studio consumption:
- `docs/specs/studio/5. Code Editor Workspace Specification.md` and `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md` now state that frontend semantic presentation is frontend-owned, derived from `FrontendSpec`, and fallback-free.
- `docs/specs/compiler-languages/pbs/README.md` now declares PBS ownership of semantic vocabulary and semantic editor presentation contract.
- `FrontendSpec` is now used as the canonical source of semantic presentation metadata consumed by the editor pipeline.
- `PBSDefinitions` publishes PBS semantic keys and resource paths, and `PbsSemanticKind` defines the stable frontend-owned semantic vocabulary.
- `prometeu-lsp` now transports frontend-owned semantic keys and exposes `LspSemanticPresentationDTO` derived from the resolved frontend spec instead of collapsing highlights into host-owned `fe-*` buckets.
- Studio consumes descriptor resources through `EditorDocumentPresentationRegistry`, projects keys mechanically through `EditorDocumentSemanticHighlighting`, and applies frontend-owned stylesheets such as PBS semantic highlight resources.
## Patterns and Algorithms
### Pattern: Treat Semantic Presentation as Language Metadata
When editor semantic styling is language-specific, the contract should live with the frontend definition rather than with the host renderer.
That keeps vocabulary, resources, and evolution under the same owner.
### Pattern: Bridge Metadata Without Reinterpreting It
The correct transport flow is:
- frontend defines semantic vocabulary and resources,
- LSP derives and transports the descriptor,
- Studio consumes and renders it mechanically.
The bridge must preserve keys, not rename them into a host dialect.
### Example: Mechanical Projection Rule
The resulting projection flow is:
1. PBS publishes a semantic key such as `pbs-function`.
2. LSP returns highlight spans with that same key and a descriptor containing PBS resources.
3. Studio projects the key to `editor-semantic-pbs-function`.
4. PBS-owned stylesheet resources style that class.
## Pitfalls
- Do not reintroduce generic host-owned semantic keys such as `fe-keyword` or `fe-type`.
- Do not move frontend semantic stylesheets back into Studio just because the renderer loads them.
- Do not treat LSP DTO ownership as presentation ownership; transport is not authorship.
- Do not add a generic fallback theme for missing frontend metadata, because that silently restores host semantic ownership.
- Do not make Studio perform deep contract validation that belongs in frontend tests.
## References
- `DEC-0012` Frontend-owned semantic editor presentation via FrontendSpec-derived descriptor
- `PLN-0026` Propagate DEC-0012 into Studio and frontend normative specs
- `PLN-0027` Add frontend semantic presentation contract to FrontendSpec and expose it through LSP
- `PLN-0028` Consume frontend-owned semantic presentation in Studio and retire generic FE theme usage
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
- `docs/specs/compiler-languages/pbs/README.md`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSDefinitions.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsSemanticKind.java`
- `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/dtos/LspSemanticPresentationDTO.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/models/SemanticIndex.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentPresentationRegistry.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/syntaxhighlight/EditorDocumentSemanticHighlighting.java`
## Takeaways
- Semantic presentation belongs to the frontend when semantic meaning belongs to the frontend.
- LSP should transport frontend-owned contracts without flattening them into host-owned categories.
- Studio stays cleaner when it renders semantic presentation mechanically and degrades to no highlight instead of inventing a fallback theme.

243
discussion/workflow/agendas/AGD-0013-studio-editor-write-wave-supported-non-frontend-files.md
View File

@ -1,243 +0,0 @@
---
id: AGD-0013
ticket: studio-editor-write-wave-supported-non-frontend-files
title: Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE
status: accepted
created: 2026-03-31
resolved: 2026-03-31
decision: DEC-0010
tags:
- studio
- editor
- workspace
- write
- read-only
- vfs
- frontend-boundary
---
## Pain
O `Code Editor` do Studio ja saiu da fase de abertura somente leitura e agora existe pressao para iniciar a wave de edicao de arquivos.
Mas o recorte pedido nao e "liberar escrita para tudo".
O recorte correto e mais estreito:
- editar apenas arquivos aceitos pelo sistema;
- manter todos os arquivos relacionados ao frontend (`FE`) em `read-only` nesta etapa;
- e evitar que o editor misture, por inferencia, tres conceitos diferentes:
- arquivo suportado para abrir,
- arquivo elegivel para highlight/presentacao,
- arquivo elegivel para mutacao e persistencia.
Se isso nao for fechado agora, a wave de escrita corre risco de nascer com uma regra pobre:
- ou o editor libera escrita para qualquer texto suportado;
- ou empilha `ifs` locais no `EditorWorkspace`;
- ou trata "arquivo do FE" apenas como detalhe visual, sem uma politica operacional clara de mutabilidade.
## Context
Domain owner: `studio`
Owner surface: `docs/specs/studio`
Superficies e referencias relevantes:
- `docs/specs/studio/5. Code Editor Workspace Specification.md` ainda trava a wave atual como `read-only`;
- `docs/specs/studio/6. Project Document VFS Specification.md` ja moveu classificacao de suporte e abertura de documento para `prometeu-vfs`;
- `discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md` consolida que a primeira wave do editor foi propositalmente somente leitura;
- `discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md` consolida que o editor deve consumir um boundary documental, nao virar owner de runtime de filesystem;
- `FilesystemProjectDocumentVfs` hoje diferencia:
- arquivos `json`/`ndjson`,
- arquivos `bash`,
- arquivos do frontend pela linguagem registrada,
- e `text` generico;
- `EditorWorkspace` ainda marca o `CodeArea` como `setEditable(false)`, ou seja, a wave de escrita exigira revisao normativa e nao apenas um ajuste tecnico.
Clarificacao importante para esta discussion:
- "arquivo aceito" nesta agenda significa arquivo que o sistema aceita abrir como documento textual no boundary atual;
- isso nao implica automaticamente que o arquivo e editavel;
- "arquivo relacionado ao FE" tambem nao pode ficar como intuicao editorial solta;
- a fronteira precisa virar regra operacional explicita, provavelmente no boundary documental ou em politica derivada dele;
- a verificacao deve ficar no `prometeu-vfs`, usando o enquadramento do `typeId` contra `allowedExtensions` do `FrontendSpec`.
## Open Questions
- [x] O criterio canonico de "arquivo aceito para edicao" deve ser o mesmo universo de documentos suportados para abrir; a politica de acesso do `prometeu-vfs` decide se cada documento suportado fica `read-only` ou `editable` nesta wave.
- [x] "Relacionado ao FE" deve ser definido no `prometeu-vfs` pelo enquadramento do `typeId` contra `allowedExtensions` do `FrontendSpec`.
- [x] Fora do escopo classificado como `FE`, a wave editavel inicial fica limitada aos tipos textuais ja suportados hoje: `text`, `json`, `ndjson` e `bash`.
- [x] O bloqueio de escrita para FE deve usar o item `read-only` na status bar, com espaco para evoluir para icone de cadeado aberto/fechado e futuro toggle de edicao; arquivos `FE` `read-only` tambem devem mostrar alerta no topo informando que nao podem ser salvos e que qualquer alteracao sera perdida.
- [x] A politica de acesso documental deve morar sempre no `prometeu-vfs`, inclusive para `load` e `save`.
- [x] A primeira wave de edicao inclui snapshot em memoria para documentos editaveis e persistencia em disco no `save` a partir desse snapshot.
- [x] O menu global `Save` nao deve ser usado para este fluxo; `save` e acao local do editor e deve viver numa barra de comandos no topo do editor, inicialmente com `Save` e `Save All`.
- [x] Tabs com arquivos FE `read-only` podem coexistir com tabs editaveis nao-FE no mesmo workspace, com estados visuais diferentes.
- [x] Os arquivos editaveis desta wave nao fazem parte da build em si.
- [x] O snapshot editavel em memoria desta wave deve permanecer contido e separado do snapshot documental usado pelos fluxos que participam da build.
## Options
### Option A - Liberar escrita para todo arquivo textual suportado
- **Approach:** Tratar todo `VfsTextDocument` como potencialmente editavel, exceto binarios ou sem handler.
- **Pro:** Menor custo inicial e quase nenhum metadado novo.
- **Con:** Viola diretamente o recorte pedido, porque arquivos de FE tambem passariam a ser editaveis ou exigiriam excecoes tardias e espalhadas.
- **Maintainability:** Baixa. A regra nasce ampla demais e depois precisa ser recortada por remendos.
### Option B - Manter suporte no VFS e derivar editabilidade so no `EditorWorkspace`
- **Approach:** O `prometeu-vfs` continua apenas dizendo se o arquivo abre, e o editor decide localmente se aquele documento fica `read-only` ou editavel.
- **Pro:** Mudanca pequena no boundary atual.
- **Con:** Regride a disciplina arquitetural recente; o editor volta a carregar regra de produto que deveria ser compartilhavel e auditavel.
- **Maintainability:** Media para baixa. Funciona rapido, mas enfraquece o boundary documental.
### Option C - Introduzir uma politica explicita de acesso documental acima do VFS
- **Approach:** Manter o `prometeu-vfs` como owner de suporte/abertura e adicionar uma classificacao explicita de `document access mode`, distinguindo ao menos `unsupported`, `read-only` e `editable`.
- **Pro:** Separa corretamente:
- abrir o documento,
- classificar o documento,
- e decidir se esta wave permite mutacao.
- **Con:** Exige desenhar melhor onde essa politica mora e como ela chega ao editor sem inflar o contrato cedo demais.
- **Maintainability:** Forte. O sistema ganha uma regra clara e evolutiva para waves futuras.
### Option D - Colocar a politica de editabilidade dentro do contrato documental do `prometeu-vfs`
- **Approach:** O proprio boundary documental passa a devolver metadados normativos de acesso, incluindo se o documento e `editable` ou `read-only` nesta wave.
- **Pro:** Mantem suporte, tipo documental e politica de acesso no mesmo owner, reduzindo ambiguidade nos consumidores.
- **Con:** Exige desenhar com cuidado o snapshot editavel em memoria, o ciclo de `save` e a fronteira do que continua fora da build.
- **Maintainability:** Forte, desde que o contrato permaneça estreito e centrado em acesso documental, nao em UX.
## Discussion
As discussoes anteriores fecharam duas coisas importantes:
1. o editor nao deve fingir semantica de IDE cedo demais;
2. o editor nao deve voltar a ser owner de concerns documentais que ja foram movidos para `prometeu-vfs`.
Isso significa que a wave de escrita precisa evitar dois erros simetricos:
- liberar mutacao ampla demais e quebrar o recorte de produto;
- ou resolver a restricao de FE com condicionais locais no `EditorWorkspace`, quebrando a separacao arquitetural que acabou de ser criada.
O ponto mais delicado aqui e que "arquivo textual aceito" e "arquivo editavel nesta etapa" ja nao sao a mesma coisa.
Hoje o sistema ja consegue abrir um conjunto de documentos textuais, inclusive documentos associados ao frontend.
Mas o pedido atual cria uma nova regra de produto:
- alguns arquivos suportados continuarao `read-only`;
- e isso nao acontece por incapacidade tecnica de abrir o arquivo, mas por decisao deliberada de wave.
Portanto, o modelo tende a precisar de uma superficie nova de classificacao.
Se ela nao existir, o editor fica tentado a usar heuristicas locais:
- `typeId == languageId`
- path em source roots
- extensao
- ou combinacoes desses sinais
Esse caminho e rapido, mas ruim.
Ele espalha a politica de mutabilidade pelo consumidor errado.
Tambem houve um fechamento importante para a decisao:
- o recorte canonico de `FE` deve ser verificado no `prometeu-vfs`;
- essa verificacao deve usar o enquadramento do `typeId` contra `allowedExtensions` do `FrontendSpec`;
- e o editor deve apenas consumir essa classificacao pronta, sem rederivar a regra localmente.
Se isso nao for fechado, o time pode permitir escrita em arquivos do frontend por acidente apenas porque eles aparecem como `text`, `json` ou outro tipo textual generico.
Outro fechamento importante desta agenda e que a primeira whitelist editavel nao cresce alem do que o produto ja suporta hoje como texto:
- `text`
- `json`
- `ndjson`
- `bash`
Ou seja, a wave inicial de edicao nao abre novo suporte documental.
Ela apenas permite mutacao em um subconjunto dos documentos textuais que ja existem hoje, excluindo o escopo classificado como `FE`.
Tambem ja existe um fechamento arquitetural relevante sobre ownership:
- a politica de acesso nao deve viver em policy layer solta no `studio`;
- `prometeu-vfs` deve ser o owner de `load`, `save` e da classificacao `read-only` versus `editable`;
- para documentos editaveis desta wave, o VFS deve manter um snapshot em memoria durante a sessao;
- quando houver `save`, o VFS persiste em disco o conteudo desse snapshot;
- o editor consome esse estado e dispara a intencao de salvar, mas nao reimplementa a politica nem o fluxo de persistencia.
Tambem ficou fechado que o universo canonico de documentos continua sendo o conjunto suportado pelo VFS.
O que muda nao e o universo de abertura, mas a politica de acesso aplicada a cada documento suportado:
- alguns suportados permanecem `read-only`, como o escopo de `FE`;
- outros suportados podem entrar como `editable` nesta wave;
- e essa decisao continua centralizada no `prometeu-vfs`.
Isso empurra a agenda com mais forca para a direcao de `Option D`.
Outro limite importante tambem ficou explicitado:
- os arquivos editaveis desta wave nao participam da build em si;
- portanto, a wave de escrita nao pode inferir integracao com pipeline, recompilacao, invalidacao de artefatos ou qualquer contrato de build;
- o escopo aqui e documental/editorial, nao de toolchain.
- isso tambem significa que o snapshot editavel em memoria nao deve se misturar com snapshots documentais ou entradas que alimentem a build;
- deve existir contencao clara entre:
- o estado editorial temporario usado pela sessao de edicao;
- e o estado documental/build-facing que outros fluxos do sistema possam consumir.
Essa contencao importa porque "ter snapshot em memoria" nao pode virar permissao implicita para o restante do produto observar rascunhos editoriais como se fossem input canonico de build.
A direcao mais coerente hoje parece ser preservar o boundary documental e introduzir um conceito explicito de politica de acesso.
Essa politica pode morar:
1. dentro do `prometeu-vfs`, se quisermos que o owner documental responda tambem pela mutabilidade da wave;
2. ou numa camada de policy ainda no dominio `studio`, mas acima do VFS, desde que o `EditorWorkspace` continue apenas consumindo a decisao pronta.
Com o fechamento atual, a agenda ja converge para descartar a segunda alternativa.
O que parece fraco e empurrar isso para o `EditorWorkspace`, e o usuario tambem ja fechou que a politica de acesso deve passar sempre por `prometeu-vfs`.
No plano de UX, a direcao tambem ficou suficiente para a proxima etapa:
- o estado `read-only` de `FE` deve aparecer na status bar;
- essa superficie pode evoluir mais tarde para um toggle explicito de habilitar/desabilitar edicao por arquivo;
- o `prometeu-vfs` deve, portanto, ja nascer pensando em contexto persistente de acesso por documento;
- `Save` e `Save All` nao pertencem ao menu global do shell e sim ao editor, em uma barra de comandos propria no topo;
- arquivos `FE` `read-only` nao podem ser salvos;
- ao abrir esse tipo de arquivo, o editor deve mostrar um alerta no topo informando que ele e `read-only` e que qualquer alteracao sera perdida.
Tambem vale registrar desde ja a implicacao para um futuro `prometeu-lsp` integrado ao Studio:
- o objetivo nao e portar o suporte das linguagens Prometeu para VSCode ou para um editor externo;
- portanto, a agenda de escrita nao deve introduzir dependencia de protocolo externo como fundamento da edicao;
- um futuro `prometeu-lsp` integrado deve ser tratado como consumidor semantico in-process ou Studio-owned acima do mesmo substrate de sessao, e nao como dono da politica de acesso documental;
- esse consumidor futuro deve observar o estado documental/snapshots editoriais necessarios para analise, sem colapsar a contencao entre estado editorial temporario e inputs canonicos de build;
- `read-only` para `FE` nesta wave significa apenas bloqueio de mutacao editorial, nao proibicao de leitura ou analise semantica futura;
- a integracao semantica continua sendo tema de decisao propria e nao deve ser inferida automaticamente a partir desta wave de escrita.
Observacao cravada para o proximo ciclo:
- quando o escopo de `FE` for liberado para edicao, o `prometeu-lsp` integrado ao Studio deve entrar em questao como consumidor do conteudo disponibilizado pelo `prometeu-vfs`;
- para documentos abertos, a analise deve enxergar o snapshot em memoria da sessao;
- para documentos nao abertos, a analise pode ler o estado em filesystem exposto pelo mesmo boundary;
- isso reforca que `prometeu-vfs` precisa permanecer como substrate documental canonico do editor e da futura analise semantica integrada.
## Resolution
Esta agenda convergiu para uma direcao suficiente para `decision`.
Recomendacao final: evoluir para uma decisao que introduza uma classificacao explicita de acesso documental para o `Code Editor`, separando:
1. arquivo nao suportado;
2. arquivo suportado porem `read-only`;
3. arquivo suportado e editavel.
Fechamentos aceitos:
- manter todo arquivo relacionado ao `FE` em `read-only` nesta wave;
- deixar o `prometeu-vfs` verificar se o `typeId` do documento cai no conjunto de `allowedExtensions` do `FrontendSpec`;
- manter como universo canonico os mesmos documentos suportados para abrir, sem criar registro paralelo de elegibilidade fora do `prometeu-vfs`;
- limitar a wave editavel inicial, fora do escopo de `FE`, aos tipos ja suportados hoje: `text`, `json`, `ndjson` e `bash`;
- fazer `prometeu-vfs` ser o owner de `load`, snapshot editavel em memoria e `save` em disco para esses documentos;
- tratar essa wave como escopo documental que nao participa da build em si;
- manter contencao explicita entre snapshot editorial em memoria e qualquer snapshot/build-input de carater canonico;
- expor o estado `read-only` de `FE` na status bar, com espaco para futura evolucao a toggle por arquivo;
- adicionar uma barra de comandos no topo do editor com `Save` e `Save All`, em vez de usar o menu global do shell;
- permitir coexistencia de tabs `read-only` de `FE` com tabs editaveis nao-`FE`;
- e mostrar alerta no topo para arquivos `FE` informando que sao `read-only`, nao podem ser salvos e que qualquer alteracao sera perdida.
- registrar que um futuro `prometeu-lsp` integrado ao Studio deve consumir o mesmo substrate de sessao/documentos sem virar owner da politica de acesso ou forcar compatibilidade com editor externo.
Next step suggestion: converter esta agenda em `decision` normativa para propagar a wave de escrita controlada do editor para specs, plano e implementacao.

165
discussion/workflow/agendas/AGD-0014-studio-editor-frontend-edit-rights.md
View File

@ -1,165 +0,0 @@
---
id: AGD-0014
ticket: studio-editor-write-wave-supported-non-frontend-files
title: Definir a fase de FE read-only com LSP minimo no Code Editor do Studio
status: accepted
created: 2026-03-31
resolved: 2026-03-31
decision: DEC-0011
tags:
- studio
- editor
- workspace
- write
- frontend-boundary
- lsp
- access-policy
---
## Pain
A agenda `AGD-0013` fechou a primeira wave de escrita deixando todo arquivo de `FE` em `read-only`.
Isso foi a decisao correta para destravar a wave inicial, e agora abre uma fase intermediaria mais segura:
- manter `FE` em `read-only`;
- introduzir um `prometeu-lsp` minimo integrado ao Studio;
- e validar o ganho semantico em cima do substrate documental do `prometeu-vfs`.
O tema de liberacao efetiva de edicao para `FE` deixa de ser escopo desta agenda.
Ele deve seguir para outra discussion propria.
## Context
Domain owner: `studio`
Owner surface: `docs/specs/studio`
Superficies e referencias relevantes:
- `AGD-0013` aceitou que, nesta wave, arquivos de `FE` permanecem `read-only`;
- `AGD-0013` tambem cravou que um futuro `prometeu-lsp` integrado ao Studio deve consumir o conteudo exposto por `prometeu-vfs`, usando snapshot em memoria para documentos abertos e filesystem para documentos fechados;
- `docs/specs/studio/6. Project Document VFS Specification.md` fecha `prometeu-vfs` como substrate documental de sessao;
- `discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md` consolida a regra de nao fingir semantica de IDE antes da hora;
- `discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md` consolida que `prometeu-lsp` deve ser consumidor futuro acima de `prometeu-vfs`, nao seu substituto;
- `prometeu-packer-api` ja oferece um exemplo util de flat packaging por superficie explicita, com pacotes como `dtos`, `messages`, `events` e subgrupos pequenos e nomeados;
- a build e a analise semantica ja precisam continuar distintas: snapshot editorial em memoria nao pode virar input canonico de build por inferencia.
Clarificacao importante desta agenda:
- esta agenda nao libera edicao de `FE`;
- esta agenda fecha apenas a fase `FE read-only + LSP minimo`;
- a futura liberacao de mutacao e `save` para `FE` deve acontecer em outra discussion propria;
- aqui o foco e definir o contrato minimo entre `prometeu-vfs` e `prometeu-lsp` integrado enquanto `FE` continua `read-only`.
## Open Questions
- [x] Pode existir uma fase intermediaria com `FE` ainda `read-only`, mas ja com `prometeu-lsp` integrado minimo consumindo o `prometeu-vfs`; o direito de edicao do `FE` continua para uma fase posterior em outra discussion.
- [x] Nesta fase `read-only`, o `prometeu-lsp` deve consumir o snapshot em memoria do `prometeu-vfs` para arquivos abertos e cair para filesystem apenas quando o arquivo estiver fechado.
- [x] O escopo minimo do `prometeu-lsp` integrado nesta fase e `diagnostics`, `symbols`/`outline`, `definition` e `highlight`.
- [x] `Completion` fica explicitamente fora desta fase minima por ainda nao existir direito de edicao de `FE`.
- [x] Nao e necessario implementar agora persistencia de contexto de acesso por documento no `prometeu-vfs`, mas ja deve existir uma entidade de contexto onde esses valores possam ser consultados e alterados sob demanda, facilitando persistencia futura.
- [x] O estado editorial em memoria de arquivos `FE` pode alimentar analise semantica sem nunca alimentar build; qualquer futura ponte com build fica fora desta agenda e de outra decisao propria.
## Options
### Option A - Misturar LSP minimo e futura liberacao de edicao na mesma agenda
- **Approach:** Tentar resolver agora tanto a fase `read-only + LSP` quanto o futuro direito de edicao de `FE`.
- **Pro:** Menos artefatos de workflow.
- **Con:** Mistura readiness semantica com mutacao editorial e amplia demais o escopo.
- **Maintainability:** Baixa. A agenda perde nitidez.
### Option B - Introduzir LSP minimo com FE ainda read-only, e liberar edicao depois em outra discussion
- **Approach:** Primeiro integrar um `prometeu-lsp` minimo ao Studio enquanto arquivos de `FE` permanecem `read-only`; so depois, em uma fase seguinte, decidir a liberacao de `save` e mutacao editorial de `FE`.
- **Pro:** Valida cedo a cadeia `prometeu-vfs` -> snapshots de sessao -> consumidor semantico, sem ainda assumir a responsabilidade de mutacao em arquivos de linguagem.
- **Con:** Cria uma fase intermediaria a mais e exige disciplina para nao tratar "LSP minimo" como permissao implicita para editar.
- **Maintainability:** Muito forte. Separa readiness semantica de direito de mutacao e reduz rework.
### Option C - Fazer uma fase minima ainda menor
- **Approach:** Limitar o LSP minimo a `diagnostics` e talvez `symbols`, deixando `definition` e `highlight` para depois.
- **Pro:** Reduz a primeira entrega semantica.
- **Con:** Pode subentregar valor perceptivel e fragmentar demais a fase minima.
- **Maintainability:** Media. So vale se a superficie tecnica ainda estiver imatura.
## Discussion
O que a discussao atual ja deixa claro e que o `FE` tem peso diferente dos outros textos suportados hoje.
Para `text`, `json`, `ndjson` e `bash`, a primeira wave editavel pode ser tratada como escopo editorial controlado:
- `prometeu-vfs` carrega;
- o editor altera;
- o `prometeu-vfs` guarda snapshot;
- e o `save` persiste em disco;
- tudo isso sem envolver build nem semantica forte.
Para `FE`, esse raciocinio parece insuficiente.
O proprio caminho que foi cravado em `AGD-0013` indica a direcao correta:
- quando `FE` for liberado, `prometeu-lsp` integrado entra em questao;
- esse LSP deve consumir o mesmo substrate documental;
- e o snapshot em memoria do VFS deve ser a verdade de analise para documentos abertos.
O refinamento trazido agora melhora essa sequencia:
- nao e necessario esperar a liberacao de edicao de `FE` para introduzir um `prometeu-lsp` minimo;
- ao contrario, ter uma fase de `FE` ainda `read-only`, mas ja observavel semanticamente, parece um passo mais seguro;
- isso deixa o time validar ingestao de snapshots, diagnosticos, outline ou outras leituras sem ainda assumir `save`, mutacao e UX de conflito para arquivos de linguagem.
Isso tambem sugere que o tema de direito de edicao do `FE` deve sair desta agenda.
Aqui basta fechar a fase de leitura semantica minima enquanto o `FE` continua bloqueado para mutacao.
Tambem importa manter o boundary certo:
- `prometeu-vfs` continua owner de documentos, snapshots e persistencia;
- `prometeu-lsp` futuro consome esse estado para analise;
- o editor continua owner de UX;
- build continua fronteira separada.
Tambem vale fechar desde ja um principio de organizacao da API:
- o `prometeu-lsp` deve usar flat packaging tomando `prometeu-packer-api` como referencia;
- isso favorece superficies explicitas para `dtos`, `messages`, `events` e tipos correlatos;
- evita esconder o contrato do LSP em arvore profunda demais ou em pacotes acidentais por feature interna;
- e ajuda a manter a fronteira publica do modulo legivel para Studio e consumidores futuros.
Se isso for respeitado, um LSP integrado proprio do Studio faz mais sentido do que qualquer adaptacao para editor externo.
O que interessa aqui e ter um consumidor semantico alinhado ao runtime documental do produto, nao compatibilidade com VSCode.
O conjunto de ganhos mais plausivel para esta fase minima e:
- `diagnostics`;
- `documentSymbol`/`workspaceSymbol` e `Outline`;
- `definition`;
- `highlight` no `FE`.
`Completion`, `rename`, code actions, formatting e direito de edicao devem ficar fora desta agenda.
Tambem ficou fechado que:
- nao precisamos implementar agora persistencia de contexto de acesso por documento no `prometeu-vfs`;
- mas ja devemos agrupar esses valores em uma mesma entidade de contexto, para que possam ser buscados e alterados sob demanda;
- isso deixa o caminho mais curto para persistir esse contexto depois, sem refazer a modelagem;
- e o contrato nao deve bloquear a futura introducao de um toggle de `read-only`/edicao por arquivo.
## Resolution
Recommended direction: seguir com **Option B**.
Direcao recomendada neste momento:
1. o `FE` permanece `read-only` nesta agenda;
2. esta agenda fecha apenas a fase de `prometeu-lsp` minimo com `FE` ainda `read-only`;
3. essa fase trata o `prometeu-lsp` integrado como consumidor do conteudo exposto por `prometeu-vfs`;
4. para documentos de `FE` abertos, a analise observa o snapshot em memoria da sessao;
5. para documentos de `FE` fechados, a analise pode cair para o estado em filesystem;
6. `prometeu-vfs` continua owner de snapshots, persistencia e politica de acesso documental;
7. `prometeu-lsp` nao vira owner de `save`, de persistencia nem de politica de acesso;
8. esta agenda mira como escopo minimo `diagnostics`, `symbols`/`outline`, `definition` e `highlight`;
9. `completion`, `rename`, code actions, formatting e a liberacao de edicao de `FE` ficam para depois;
10. a futura liberacao de edicao de `FE` deve acontecer em outra discussion propria;
11. nenhuma fase desta agenda pode misturar automaticamente snapshot editorial com input canonico de build.
12. a API de `prometeu-lsp` deve preferir flat packaging no estilo de `prometeu-packer-api`, com superficies explicitas como `dtos`, `messages` e `events`.
13. o `prometeu-vfs` nao precisa implementar agora contexto persistente de acesso por documento, mas deve introduzir uma entidade de contexto unica para esses valores, de modo que leitura/mutacao sob demanda ja exista e a persistencia futura seja uma extensao natural.
Next step suggestion: converter esta agenda em `decision` normativa para a fase `FE read-only + LSP minimo`, deixando a futura liberacao de edicao de `FE` para outra discussion.

223
discussion/workflow/agendas/AGD-0015-studio-frontend-owned-semantic-editor-presentation.md
View File

@ -1,223 +0,0 @@
---
id: AGD-0015
ticket: studio-frontend-owned-semantic-editor-presentation
title: Definir ownership do schema visual semantico do editor por frontend
status: accepted
created: 2026-04-02
resolved: 2026-04-02
decision: DEC-0012
tags:
- studio
- editor
- frontend
- presentation
- semantic-highlighting
- compiler
- pbs
---
## Pain
Hoje o Code Editor do Studio aplica um schema visual generico de frontend em `prometeu-studio/src/main/resources/themes/editor/presentations/fe.css`.
Isso resolve a primeira wave de consumo semantico, mas deixa a responsabilidade errada:
- o Studio hospeda o renderer;
- o LSP/FE emite chaves semanticas;
- mas a cor final fica centralizada num tema generico do Studio;
- e a linguagem concreta perde ownership editorial sobre sua propria aparencia semantica.
Na pratica, isso significa que PBS esta sendo colorido por um tema global de `FE`, mesmo sendo a propria FE que sabe quais categorias devem existir, quais cores fazem sentido e como essa linguagem quer ser lida.
## Context
Domain owner: `studio`
Owner surface: `discussion/...` agora; futuras propagacoes normativas devem atingir `docs/specs/studio` e, se necessario, specs do dominio `compiler/<language>`.
Superficies e referencias relevantes:
- `DEC-0011` aceitou a fase minima de FE read-only com diagnostics, symbols, definition e highlight no editor;
- o Studio hoje resolve qualquer frontend para uma presentation unica `fe` em `EditorDocumentPresentationRegistry`;
- o tema visual semantico dessa presentation esta em `prometeu-studio/src/main/resources/themes/editor/presentations/fe.css`;
- as semantic keys atuais sao emitidas pelo LSP em `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/models/SemanticIndex.java`;
- PBS e hoje a unica FE integrada ao Studio, mas o desenho do editor foi aberto como multi-frontend desde as foundations do workspace;
- `studio` deve continuar owner da superficie de renderizacao do editor, mas isso nao implica ownership do schema visual normativo de cada linguagem.
Clarificacoes importantes:
- esta agenda nao discute edit rights de FE;
- esta agenda nao rediscute `DEC-0011`;
- esta agenda trata de ownership editorial e contrato de presentation para highlight semantico no editor;
- o owner principal do workflow continua `studio`, com referencia explicita ao dominio `compiler/<language>` para assets ou contratos language-owned.
## Open Questions
- [x] O schema visual semantico de uma linguagem deve ser owner da FE especifica em vez de um tema generico do Studio.
- [x] O Studio nao deve ser owner de stylesheet semantico de FE; ele deve apenas consumir o contrato resolvido pelo hub LSP.
- [x] O LSP tambem nao deve ser owner de recursos da FE; ele deve agir como hub/contrato entre FE e Studio.
- [x] Cada FE deve publicar sua propria semantica e seu proprio CSS de highlight acompanhando a FE.
- [x] O LSP nao deve reduzir a semantica da FE para um set comum artificial como `fe-keyword`, `fe-type` ou equivalentes.
- [x] Nao deve haver fallback visual generico; se a FE nao publicar, ou se nao houver recurso usavel, o Studio simplesmente nao aplica semantic highlight.
- [x] A FE deve produzir semantic keys a partir de um vocabulário semântico language-owned, por exemplo `PbsSemanticKind`, usando `semanticKey` como forma contratual estavel e nao algo presentation-owned como `cssKey`.
- [x] O casamento entre semantic key e CSS acontece no Studio apenas como projecao mecanica de classe, sem traducao semantica intermediaria.
- [x] O hub LSP deve expor esse contrato para o Studio por meio de um descriptor proprio, produzido a partir do `FrontendSpec` vindo da analise.
- [x] O shape inicial desse descriptor deve permanecer completo, mas simples: semantic keys + resources, ambos dentro de uma mesma mensagem/descriptor para facilitar evolucao futura.
- [x] O Studio nao deve fazer validacao profunda do contrato; aceita o que houver e, se nao houver contract/resource usavel, simplesmente nao destaca semanticamente.
- [x] Nao deve existir erro de contrato exposto no Studio; no maximo, log comum de desenvolvimento.
- [x] Os assets da FE devem viver em `resources/` e ser resolvidos como qualquer outro resource Java.
- [x] O contrato deve viver no `FrontendSpec`, que continua como superficie estatica.
- [x] A presenca e consistencia minima desse contrato no `FrontendSpec` podem ser validadas por testes da propria FE.
- [x] Se semantic keys ou resources estiverem ausentes em runtime, o Studio segue sem highlight em vez de falhar.
## Options
### Option A - Manter schema visual generico de FE no Studio
- **Approach:** Continuar com `fe.css` como presentation unica para qualquer linguagem frontend, mantendo o Studio como owner das cores e aceitando uma taxonomia reduzida comum.
- **Pro:** Implementacao simples e baixo churn imediato.
- **Con:** A FE continua sem ownership sobre sua propria apresentacao semantica e o Studio acumula regra editorial que nao lhe pertence.
- **Maintainability:** Fraca. Escala mal quando houver mais de uma linguagem.
### Option B - FE publica semantica e presentation proprias, LSP atua como hub contratual
- **Approach:** Cada frontend publica sua taxonomia semantica real e seus resources de presentation proprios; a semantic key nasce de um vocabulário language-owned da FE; o contrato vive de forma estatica no `FrontendSpec`; o LSP produz, a partir do `FrontendSpec` resolvido na analise, um descriptor proprio com semantic keys + resources e expõe isso ao Studio sem reduzir a linguagem a um set comum artificial e sem capturar ownership de recursos.
- **Pro:** Ownership correto, melhor escalabilidade multi-frontend e capacidade de cada linguagem definir sua propria identidade visual e suas categorias.
- **Con:** Exige um contrato novo e mais explicito entre FE, LSP e Studio.
- **Maintainability:** Forte. Separa host UI de schema semanticamente owner-driven.
### Option C - Studio continua owner do CSS, mas por frontend especifico
- **Approach:** O Studio deixa de ter um unico `fe.css` e passa a manter `pbs.css`, `foo.css`, etc., ainda sob ownership do modulo Studio.
- **Pro:** Melhora a diferenciacao por linguagem com mudanca tecnica pequena.
- **Con:** Corrige o sintoma, nao a fronteira de ownership. O Studio continuaria decidindo visual de linguagem.
- **Maintainability:** Media. Menos acoplado que hoje, mas ainda ownership errado.
## Discussion
O problema real aqui nao e "qual azul usar para keyword".
O problema e quem e responsavel por declarar a semantica e o schema visual de uma categoria semantica.
Hoje, o pipeline esta dividido assim:
- a FE/LSP identifica categorias semanticas;
- o Studio renderiza spans;
- o tema final vem de um CSS generico de frontend.
Isso foi um atalho razoavel para a primeira fase, mas entra em conflito com o desenho multi-frontend do editor.
Se mais uma linguagem entrar, o `fe.css` inevitavelmente vira:
- denominador comum fraco;
- ou lugar de negociacao editorial entre linguagens;
- ou conjunto de excecoes por linguagem escondidas num host que nao deveria ser owner disso.
Option C parece tentadora porque reduz impacto tecnico:
- sair de `fe.css` para `pbs.css`;
- manter o Studio resolvendo presentation por tipo;
- e encerrar o assunto.
Mas isso nao fecha a questao conceitual.
Ainda seria o Studio definindo a paleta normativa da FE.
O acoplamento mudaria de "frontend generico" para "frontend por linguagem, mas ainda host-owned".
O recorte que voce fechou agora deixa a fronteira desejada bem mais objetiva:
- cada FE deve publicar sua propria semantica;
- cada FE deve publicar o CSS proprio que sabe highlightar essa semantica;
- cada FE deve gerar semantic keys a partir de um vocabulário semântico próprio e estável;
- o LSP deve agir como hub/contrato que liga metadados e presentation da FE ao Studio e vice-versa;
- o Studio nao deve ser owner de nenhum recurso da FE;
- o LSP tambem nao deve ser owner de nenhum recurso da FE.
Tambem ficou explicitamente rejeitada a ideia de o LSP reduzir a FE a um vocabulário comum artificial como `fe-keyword`, `fe-type`, `fe-callable` e semelhantes.
Esse tipo de normalizacao achataria a linguagem e recolocaria ownership semantico no lugar errado.
O LSP deve transportar o contrato da FE, nao reinterpretar a FE em um dialeto comum do Studio.
Option B parece a direcao correta porque preserva as fronteiras certas:
- o Studio continua dono do editor, layout, interacao, status bar, warning surfaces e plumbing de style application;
- a FE passa a publicar a semantica e a presentation semantica que lhe pertencem;
- o LSP vira a ponte contratual entre FE e Studio, sem capturar ownership do asset;
- a ausencia de presentation propria nao gera fallback generico; apenas desliga semantic highlight.
Tambem importa decidir o nivel do contrato.
Ha pelo menos duas camadas diferentes:
1. taxonomia semantica
- quais chaves existem e como a FE as nomeia
- essa camada agora passa a ser explicitamente language-owned
- o hub LSP nao deve colapsar essas chaves em um set comum artificial
- a forma contratual recomendada para cada item e `semanticKey`, nao `cssKey`, porque a mesma chave pode servir a mais de um consumer
2. presentation
- como essas chaves sao coloridas/estilizadas
- essa camada tambem passa a ser explicitamente language-owned
- o CSS consome semantic keys declaradas pela FE; ele nao define o vocabulário semanticamente owner
O que permanece em aberto nao e mais o ownership.
O ownership ficou claro.
O shape do contrato tambem ficou suficientemente delineado:
- deve existir um descriptor proprio;
- esse descriptor deve ser produzido a partir do `FrontendSpec` resolvido durante a analise;
- o contrato fonte continua vivendo no `FrontendSpec`, que permanece estatico;
- o shape inicial deve ser simples: semantic keys + resources;
- semantic keys e resources devem estar juntos em uma unica mensagem/descriptor para facilitar evolucao futura;
- os resources devem viver junto da FE em `resources/`;
- o Studio consome o descriptor e tenta carregar o que existir;
- se nao houver descriptor ou resource usavel, simplesmente nao aplica highlight.
A ligacao entre semantica concreta e stylesheet tambem ficou melhor definida:
- a FE classifica semanticamente seus elementos usando um vocabulário proprio, por exemplo `PbsSemanticKind`;
- cada `SemanticKind` da FE deve expor uma `semanticKey` estavel;
- o LSP transporta essa `semanticKey` como parte do highlight semantico;
- o Studio nao traduz a key para outro dialeto semantico;
- o Studio apenas projeta a key para uma classe CSS por regra mecanica;
- o CSS publicado pela FE estiliza essa classe correspondente.
Exemplo de direcao:
- `PbsSemanticKind.FUNCTION -> semanticKey = "pbs-function"`
- o LSP envia `"pbs-function"`
- o Studio projeta para uma classe como `editor-semantic-pbs-function`
- o CSS da FE PBS define essa classe
Tambem ficou claro onde esse material vive fisicamente:
- o asset deve acompanhar a FE;
- o lugar natural e `resources/` da propria FE;
- a resolucao deve seguir o fluxo normal de resources Java;
- o Studio nao precisa inventar loader especial fora dessa convencao.
A estrategia de robustez tambem ficou fechada:
- o `FrontendSpec` pode e deve ser coberto por testes da FE para garantir a presenca minima desse contrato;
- isso permite detectar omissoes cedo sem transformar o Studio em validador pesado;
- em runtime, ausencia de semantic keys, resources ou casamento suficiente nao bloqueia o editor;
- o comportamento final continua sendo degradar para "sem highlight".
## Resolution
Recommended direction: seguir com **Option B**.
Direcao recomendada neste momento:
1. o schema visual semantico nao deve permanecer como responsabilidade generica do Studio;
2. cada FE deve publicar sua propria semantica;
3. cada FE deve publicar seu proprio CSS de highlight acompanhando a FE;
4. o LSP deve atuar como hub/contrato entre FE e Studio, expondo os metadados necessarios para o editor sem reduzir a linguagem a um set comum artificial;
5. as semantic keys devem nascer de vocabulário language-owned da FE, por exemplo `SemanticKind -> semanticKey`;
6. o Studio deve continuar apenas como host do renderer e consumidor desse contrato;
7. o casamento entre semantic key e CSS deve acontecer no Studio apenas como projecao mecanica de classe, sem traducao semantica intermediaria;
8. nem Studio nem LSP devem ser owners de qualquer recurso da FE;
9. o contrato de semantic presentation deve viver no `FrontendSpec`, que permanece uma superficie estatica;
10. o LSP deve expor ao Studio um descriptor proprio de semantic presentation, produzido a partir do `FrontendSpec` resolvido na analise;
11. o shape inicial desse descriptor deve permanecer simples: semantic keys + resources;
12. semantic keys e resources devem fazer parte de uma unica mensagem/descriptor para facilitar evolucao futura;
13. os assets da FE devem viver em `resources/` da propria FE e ser resolvidos como qualquer outro resource Java;
14. o `FrontendSpec` e esse contrato podem ser cobertos por testes da propria FE;
15. o Studio nao deve fazer validacao profunda desse contrato; se houver descriptor e resource usavel, aplica highlight; se nao houver, nao aplica;
16. nao deve existir fallback generico que substitua a presentation da FE por um schema comum do host;
17. falhas nessa publicacao nao devem virar erro de UI no Studio; no maximo, log comum de desenvolvimento;
18. a agenda esta convertida em `DEC-0012`;
19. a propagacao futura provavelmente toca `docs/specs/studio` e tambem superfícies normativas do dominio `compiler/<language>`.
Next step suggestion: converter esta agenda em `decision` normativa sobre ownership da presentation semantica por FE, fechando o descriptor produzido a partir de `FrontendSpec` e o comportamento "sem contract/resource -> sem highlight".

136
discussion/workflow/decisions/DEC-0010-studio-controlled-non-frontend-editor-write-wave.md
View File

@ -1,136 +0,0 @@
---
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.

155
discussion/workflow/decisions/DEC-0011-studio-frontend-read-only-minimum-lsp-phase.md
View File

@ -1,155 +0,0 @@
---
id: DEC-0011
ticket: studio-editor-write-wave-supported-non-frontend-files
title: Establish the frontend read-only minimum LSP phase in Studio
status: accepted
created: 2026-03-31
accepted: 2026-03-31
agenda: AGD-0014
plans:
- PLN-0022
- PLN-0023
- PLN-0024
- PLN-0025
tags:
- 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.
11. Highlight for non-frontend documents MAY remain Studio-local as currently implemented in this phase.
12. 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.
13. `Completion` SHALL remain out of scope for this minimum `read-only` phase.
14. `Rename`, code actions, formatting, and any frontend edit-right release SHALL remain out of scope for this phase.
15. The future release of frontend editing SHALL be handled by a separate discussion and decision.
16. The editorial in-memory state observed by `prometeu-lsp` MAY feed semantic analysis, but MUST NOT be treated as canonical build input by implication.
17. Any future bridge between frontend editorial state and build-facing state SHALL require a separate explicit decision.
18. `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.
19. `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.

142
discussion/workflow/decisions/DEC-0012-frontend-owned-semantic-editor-presentation.md
View File

@ -1,142 +0,0 @@
---
id: DEC-0012
ticket: studio-frontend-owned-semantic-editor-presentation
title: Frontend-owned semantic editor presentation via FrontendSpec-derived descriptor
status: accepted
created: 2026-04-02
accepted: 2026-04-02
agenda: AGD-0015
plans:
- PLN-0026
- PLN-0027
- PLN-0028
tags:
- studio
- editor
- frontend
- presentation
- semantic-highlighting
- compiler
- pbs
---
## Decision
The semantic editor presentation for frontend documents SHALL be frontend-owned.
Normative decision:
1. Each frontend MUST publish its own semantic vocabulary.
2. Each frontend MUST publish its own semantic highlight resources.
3. Neither Studio nor LSP SHALL own frontend semantic presentation assets.
4. The canonical source of this contract MUST live in `FrontendSpec`.
5. LSP MUST act only as a hub/contract bridge between frontend metadata and Studio consumption.
6. LSP MUST NOT reduce frontend semantics into a shared artificial vocabulary such as `fe-keyword`, `fe-type`, or equivalent host-owned categories.
7. Studio MUST consume the frontend semantic presentation contract without reinterpreting frontend semantics.
8. Studio MUST project semantic keys to CSS classes mechanically, without semantic translation tables.
9. If semantic presentation metadata or usable resources are absent at runtime, Studio SHALL not apply semantic highlight for that frontend document.
10. Studio MUST NOT replace missing frontend presentation with a generic host-owned fallback theme.
## Rationale
The prior arrangement centralized frontend semantic colors in Studio under a generic `fe.css` presentation. That arrangement was acceptable as an early integration shortcut, but it violates the intended boundary of a multi-frontend editor:
- Studio owns rendering surfaces and editor UX.
- The frontend owns semantic meaning.
- Semantic presentation is part of that frontend-owned meaning.
If Studio remains the owner of semantic presentation, every additional frontend either:
- collapses into a weak common denominator,
- negotiates language-specific editorial rules inside the host,
- or forces Studio to accumulate language-owned semantics.
That is the wrong ownership direction.
LSP is also not the correct owner. Its role in this design is to bridge frontend analysis products into host consumption, not to normalize, reinterpret, or host language assets.
This decision therefore locks the boundary as follows:
- frontend owns semantic vocabulary,
- frontend owns semantic presentation assets,
- `FrontendSpec` is the canonical contract source,
- LSP derives and transports a consumable descriptor,
- Studio renders what the frontend publishes.
## Technical Specification
### 1. Canonical Contract Source
1. `FrontendSpec` MUST carry the semantic presentation contract.
2. `FrontendSpec` SHALL remain a static specification surface.
3. The semantic presentation contract MUST be frontend-owned and versionable together with the frontend.
### 2. Contract Shape
The initial semantic presentation contract MUST remain simple but complete.
It SHALL include, at minimum:
1. `semanticKeys`
2. `resources`
These fields MUST be carried inside a single descriptor/message so the contract can evolve without scattering related presentation metadata across multiple unrelated surfaces.
At minimum:
- `semanticKeys` defines the frontend-owned stable semantic keys consumable by the editor pipeline.
- `resources` defines the frontend-owned presentation resources, including the stylesheet resource used for semantic highlight.
### 3. Frontend Semantic Vocabulary
1. Semantic keys MUST be produced from a frontend-owned semantic vocabulary, for example `SemanticKind -> semanticKey`.
2. A semantic key MUST be stable enough to serve as contract output.
3. The name of this contract field SHOULD be `semanticKey`, not `cssKey`, because the key is not owned by CSS and may serve multiple consumers.
### 4. LSP Responsibility
1. LSP MUST derive a semantic presentation descriptor from the `FrontendSpec` resolved during analysis.
2. LSP MUST expose that descriptor to Studio.
3. LSP MUST NOT translate frontend semantic keys into host-owned generic categories.
4. LSP MUST NOT become the owner of frontend stylesheets or semantic resources.
### 5. Studio Responsibility
1. Studio MUST remain the owner of rendering, style application, and editor UI plumbing.
2. Studio MUST NOT define frontend semantic vocabulary.
3. Studio MUST map semantic keys into CSS classes mechanically.
4. That mapping MUST be syntactic only, not semantic.
Illustrative direction:
- frontend semantic key: `pbs-function`
- Studio-applied class: `editor-semantic-pbs-function`
The exact class projection convention MAY be specified later, but the projection MUST remain mechanical and MUST NOT introduce host-owned semantic translation.
### 6. Resource Ownership and Resolution
1. Frontend semantic presentation resources MUST live under the frontend's own `resources/` surface.
2. These resources MUST be resolved like ordinary Java resources.
3. Studio and LSP MUST consume these resources through the contract and MUST NOT duplicate or host them as owners.
### 7. Validation and Runtime Behavior
1. Deep runtime validation in Studio is NOT required.
2. Frontend teams SHOULD cover semantic presentation publication with frontend tests.
3. If descriptor data is present and resources are usable, Studio SHOULD apply semantic highlight.
4. If descriptor data is absent or resources are unusable, Studio SHALL continue without semantic highlight.
5. This condition MUST NOT surface as a product-facing Studio error.
6. At most, normal development logs MAY record the condition.
## Constraints
1. This decision does NOT change FE edit rights.
2. This decision does NOT revise `DEC-0011`; it refines ownership and contract shape for semantic presentation only.
3. This decision MUST NOT be implemented by reintroducing a generic host-owned `fe.css` fallback.
4. This decision MUST NOT be implemented by collapsing language semantics into generic host-owned semantic buckets.
5. Any future expansion of the descriptor MUST preserve frontend ownership and the single-descriptor principle established here.
## Revision Log
- 2026-04-02: Initial accepted decision from AGD-0015.

115
discussion/workflow/plans/PLN-0019-propagate-dec-0010-into-studio-and-vfs-specs.md
View File

@ -1,115 +0,0 @@
---
id: PLN-0019
ticket: studio-editor-write-wave-supported-non-frontend-files
title: Propagate DEC-0010 into Studio editor and VFS specs
status: done
created: 2026-03-31
completed: 2026-03-31
tags: [studio, editor, vfs, specs, write-wave]
---
## Objective
Make the controlled non-frontend write wave normative across the Studio and VFS spec corpus before code changes begin.
## Background
DEC-0010 locks a new first write wave for non-frontend textual documents, keeps frontend files hard `read-only`, moves access policy and save ownership into `prometeu-vfs`, and requires a local editor command bar rather than the global shell save surface.
The current Studio/VFS specs still describe the first editor wave as read-only and do not yet express:
- canonical frontend classification through `FrontendSpec.allowedExtensions`,
- VFS-owned access policy,
- hard frontend `read-only`,
- editor-local `Save` and `Save All`,
- or the non-build editorial boundary for in-memory write snapshots.
## Scope
### Included
- update Studio specs to reflect the controlled write wave
- update VFS specification text for canonical frontend scope and access policy
- update spec index/read order if document ordering changes
### Excluded
- code implementation
- LSP semantic-read phase wording from DEC-0011
- any frontend edit-right release
## Execution Steps
### Step 1 - Update the Code Editor Workspace Specification
**What:**
Replace the current read-only-first-wave wording with the DEC-0010 controlled write-wave contract.
**How:**
Amend the editor spec so it states:
- non-frontend supported text classes may be editable,
- frontend files remain hard `read-only`,
- save actions live in an editor-local command bar,
- mixed editable and `read-only` tabs are allowed,
- frontend warnings and status-bar presentation are explicit.
**File(s):**
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
### Step 2 - Update the Project Document VFS Specification
**What:**
Make the VFS spec the normative home for access policy and canonical frontend scope.
**How:**
Amend the VFS spec to state:
- `FrontendSpec.allowedExtensions` is the source of truth,
- VFS must expose a canonical frontend-compatible `typeId` or equivalent scope marker,
- VFS owns access policy and save for editable non-frontend documents,
- editorial snapshots stay out of build-facing state.
**File(s):**
- `docs/specs/studio/6. Project Document VFS Specification.md`
### Step 3 - Update Shell-Level and Index Documentation
**What:**
Keep the Studio spec corpus navigable after the write-wave decision lands.
**How:**
Update any shell-level wording and read-order/index docs that still imply the editor is fully read-only.
**File(s):**
- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md`
- `docs/specs/studio/README.md`
## Test Requirements
### Unit Tests
- none
### Integration Tests
- none
### Manual Verification
- verify the spec set no longer contradicts DEC-0010 on read-only versus editable scope
- verify frontend hard `read-only` and editor-local save surfaces are both explicit
- verify build separation for editorial snapshots is stated unambiguously
## Acceptance Criteria
- [ ] Studio specs reflect the controlled non-frontend write wave
- [ ] VFS specs state `FrontendSpec.allowedExtensions` as source of truth for frontend scope
- [ ] editor-local `Save` and `Save All` are normatively placed in the editor, not the shell menu
- [ ] hard frontend `read-only` is stated consistently across Studio and VFS specs
- [ ] editorial in-memory snapshots are explicitly separated from build-facing state
## Dependencies
- DEC-0010 accepted
## Risks
- stale read-only wording may remain in sibling specs and confuse implementation
- weak wording around canonical frontend scope could reintroduce contract ambiguity
- editor-local save surfaces may be described inconsistently if shell docs are not updated

128
discussion/workflow/plans/PLN-0020-build-dec-0010-vfs-access-policy-and-save-core.md
View File

@ -1,128 +0,0 @@
---
id: PLN-0020
ticket: studio-editor-write-wave-supported-non-frontend-files
title: Build DEC-0010 VFS access policy and save core
status: done
created: 2026-03-31
completed: 2026-03-31
tags: [studio, editor, vfs, write-wave, save, access-policy]
---
## Objective
Implement the VFS-side contract required by DEC-0010: canonical frontend scope, access policy classification, editable snapshots, and save-to-disk ownership.
## Background
DEC-0010 makes `prometeu-vfs` the owner of:
- frontend scope classification from `FrontendSpec.allowedExtensions`,
- canonical access policy per supported document,
- editable in-memory document snapshots for non-frontend supported text classes,
- and save persistence for those documents.
That work must land before editor UI code can consume the new write-wave behavior safely.
## Scope
### Included
- add VFS access-policy models
- evolve VFS document/type contract so frontend scope is canonical
- add snapshot mutation and save operations for editable non-frontend docs
- add the document-access context entity reserved by the decision
- update and expand VFS tests
### Excluded
- editor command-bar UI
- LSP API or semantic-read behavior
- frontend editing
## Execution Steps
### Step 1 - Extend the Public VFS API
**What:**
Add the public contract needed for access policy, editable snapshots, and save.
**How:**
Extend `prometeu-vfs-api` with:
- an explicit access-mode model,
- canonical frontend scope exposure through `typeId` or equivalent scope marker,
- document mutation/update operations for editable docs,
- save and save-all oriented commands,
- a document-access context entity that can be read and mutated now and persisted later.
**File(s):**
- `prometeu-vfs/prometeu-vfs-api/src/main/java/p/studio/vfs/**`
### Step 2 - Implement the Filesystem-Backed VFS Behavior
**What:**
Teach the filesystem-backed VFS to enforce DEC-0010 semantics.
**How:**
Update the VFS implementation so it:
- derives frontend scope from `FrontendSpec.allowedExtensions`,
- exposes canonical scope information through the VFS contract,
- rejects local mutation for hard `read-only` frontend docs,
- keeps editable non-frontend session snapshots in memory,
- persists those snapshots to disk on save.
**File(s):**
- `prometeu-vfs/prometeu-vfs-v1/src/main/java/p/studio/vfs/FilesystemProjectDocumentVfs.java`
- `prometeu-vfs/prometeu-vfs-v1/src/main/java/p/studio/vfs/FilesystemProjectDocumentVfsFactory.java`
### Step 3 - Add Conformance Tests
**What:**
Prove the VFS now owns the right boundary.
**How:**
Add tests that cover:
- frontend scope classification from `allowedExtensions`,
- hard `read-only` refusal for frontend docs,
- editable snapshots for non-frontend supported docs,
- save persistence,
- separation between editorial snapshots and fresh filesystem state where applicable,
- access-context lookup and mutation.
**File(s):**
- `prometeu-vfs/prometeu-vfs-v1/src/test/java/p/studio/vfs/FilesystemProjectDocumentVfsTest.java`
- new `prometeu-vfs/**` test files as needed
## Test Requirements
### Unit Tests
- access-policy classification
- frontend hard `read-only` behavior
- editable snapshot update/save behavior
- access-context read/mutate behavior
### Integration Tests
- filesystem-backed save roundtrip for editable non-frontend docs
### Manual Verification
- confirm editable non-frontend docs roundtrip through save
- confirm frontend docs stay non-mutable at the VFS boundary
## Acceptance Criteria
- [ ] VFS exposes canonical access policy for supported documents
- [ ] frontend scope derives from `FrontendSpec.allowedExtensions`
- [ ] frontend docs are hard `read-only` at the VFS boundary
- [ ] editable non-frontend docs have in-memory snapshots and save through VFS
- [ ] a single access-context entity exists for current read/mutate demand
## Dependencies
- DEC-0010 accepted
- PLN-0019 review completed or otherwise stable enough for implementation
## Risks
- overloading `typeId` incorrectly could break existing presentation routing
- save semantics could leak into frontend scope if access policy is not enforced centrally
- snapshot/context modeling could become too broad if it starts anticipating future LSP needs prematurely

136
discussion/workflow/plans/PLN-0021-integrate-dec-0010-editor-write-ui-and-workflow.md
View File

@ -1,136 +0,0 @@
---
id: PLN-0021
ticket: studio-editor-write-wave-supported-non-frontend-files
title: Integrate DEC-0010 editor write UI and workflow in Studio
status: done
created: 2026-03-31
completed: 2026-03-31
tags: [studio, editor, ui, save, read-only, write-wave]
---
## Objective
Make the Studio editor consume the DEC-0010 VFS write contract and expose the intended UI workflow for editable non-frontend documents and hard frontend `read-only` documents.
## Background
Once VFS access policy and save behavior exist, the editor still needs to:
- stop being globally read-only,
- surface mixed editable and frontend hard `read-only` tabs correctly,
- expose editor-local save commands,
- and keep frontend warnings/status consistent with the decision.
## Scope
### Included
- wire editor UI to new VFS access policy and save commands
- add editor-local `Save` and `Save All` command bar
- keep frontend docs hard `read-only`
- show frontend top warning and status-bar state
- update editor tests
### Excluded
- LSP integration
- frontend editing
- shell-global menu save behavior beyond remaining unused for this flow
## Execution Steps
### Step 1 - Rewire Editor Session State Around Access Policy
**What:**
Make the editor session aware of document access mode and save capability.
**How:**
Update open-file/session models so they track:
- document access mode,
- save eligibility,
- frontend hard `read-only` state,
- and editor-local command enablement.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorOpenFileBuffer.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorOpenFileSession.java`
### Step 2 - Add the Editor Command Bar and Save Flow
**What:**
Expose the write commands in the editor itself.
**How:**
Add a top command bar or equivalent editor-local surface with `Save` and `Save All`, wired to VFS save operations for editable non-frontend docs only.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
- new `prometeu-studio/src/main/java/p/studio/workspaces/editor/**` command-bar surface as needed
- `prometeu-studio/src/main/resources/themes/default-prometeu.css`
### Step 3 - Enforce Hard Frontend Read-Only in the Editor UX
**What:**
Make frontend files visibly hard `read-only`.
**How:**
Ensure FE files:
- cannot be mutated in the editor UI,
- show `read-only` in the status bar,
- show the required top warning,
- and can coexist with editable non-frontend tabs without ambiguity.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorStatusBar.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorTabStrip.java`
### Step 4 - Update Editor Tests
**What:**
Keep editor tests focused on editor-owned behavior under the new mixed access-mode workflow.
**How:**
Add or adjust tests for:
- editable non-frontend save command routing,
- FE hard `read-only` UI state,
- mixed tab behavior,
- command enablement.
**File(s):**
- `prometeu-studio/src/test/java/p/studio/workspaces/editor/**`
## Test Requirements
### Unit Tests
- mixed access-mode tab/session behavior
- save command enablement
- FE hard `read-only` presentation state
### Integration Tests
- editor workspace integration against a VFS test double exposing editable and hard `read-only` docs
### Manual Verification
- open editable `json`/`bash`/`text` docs and confirm save works
- open FE docs and confirm they cannot be edited
- confirm FE warning and status-bar state are visible
## Acceptance Criteria
- [ ] editor consumes VFS access policy instead of local editability inference
- [ ] `Save` and `Save All` live in the editor UI
- [ ] FE docs are hard `read-only` in actual editor interaction
- [ ] mixed editable and FE `read-only` tabs behave coherently
- [ ] editor tests cover the new workflow
## Dependencies
- DEC-0010 accepted
- PLN-0020 review completed or otherwise stable enough for UI integration
## Risks
- UI may accidentally permit FE mutation if command enablement and editor mutability diverge
- save flow could become split-brained if some callsites bypass editor-local commands
- warning/status surfaces may drift if they are implemented independently

102
discussion/workflow/plans/PLN-0022-propagate-dec-0011-into-studio-vfs-and-lsp-specs.md
View File

@ -1,102 +0,0 @@
---
id: PLN-0022
ticket: studio-editor-write-wave-supported-non-frontend-files
title: Propagate DEC-0011 into Studio, VFS, and LSP specs
status: done
created: 2026-03-31
completed: 2026-03-31
tags: [studio, lsp, vfs, specs, frontend-boundary]
---
## Objective
Make the frontend read-only minimum LSP phase normative in the Studio/VFS spec corpus and establish the intended LSP contract shape before implementation.
## Background
DEC-0011 introduces a dedicated phase:
- FE remains hard `read-only`,
- `prometeu-lsp` consumes VFS snapshots,
- the minimum feature set is diagnostics, symbols/outline, definition, and frontend highlight,
- non-frontend highlight may remain Studio-local,
- and the API should follow flat packaging similar to `prometeu-packer-api`.
## Scope
### Included
- propagate DEC-0011 into Studio and VFS specs
- introduce or update LSP-facing specification text
- document flat packaging and minimum LSP scope
### Excluded
- code implementation
- frontend edit-right release
- completion
## Execution Steps
### Step 1 - Update Studio Editor and VFS Specifications
**What:**
Add the new frontend semantic-read phase to the existing Studio/VFS spec set.
**How:**
Amend the relevant specs so they explicitly state:
- FE remains hard `read-only`,
- LSP consumes VFS snapshots,
- non-frontend highlight remains local for now,
- frontend highlight comes from LSP semantics.
**File(s):**
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `docs/specs/studio/6. Project Document VFS Specification.md`
### Step 2 - Introduce an LSP-Focused Studio Specification
**What:**
Create a normative home for the integrated LSP phase.
**How:**
Add a Studio spec that defines:
- integrated `prometeu-lsp` role,
- read-only FE semantic phase,
- minimum capability set,
- flat packaging expectation,
- and explicit non-goals such as completion and frontend editing.
**File(s):**
- new `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
- `docs/specs/studio/README.md`
## Test Requirements
### Unit Tests
- none
### Integration Tests
- none
### Manual Verification
- verify no contradiction exists between DEC-0010 and DEC-0011 in the specs
- verify the new spec makes the minimum LSP scope and exclusions explicit
## Acceptance Criteria
- [ ] the Studio spec set reflects the FE read-only minimum LSP phase
- [ ] frontend highlight ownership is clearly separated from Studio-local non-frontend highlight
- [ ] LSP flat packaging is stated normatively enough to guide implementation
- [ ] completion and frontend edit rights remain explicitly out of scope
## Dependencies
- DEC-0011 accepted
- DEC-0010 stable enough to provide the underlying VFS/write boundary
## Risks
- spec propagation may accidentally imply frontend editing
- lack of a dedicated LSP spec could bury too much behavior in editor/VFS docs
- packaging guidance may stay too vague if not stated explicitly

110
discussion/workflow/plans/PLN-0023-scaffold-flat-packed-prometeu-lsp-api-and-session-seams.md
View File

@ -1,110 +0,0 @@
---
id: PLN-0023
ticket: studio-editor-write-wave-supported-non-frontend-files
title: Scaffold flat-packed prometeu-lsp API and Studio session seams
status: done
created: 2026-03-31
completed: 2026-03-31
tags: [studio, lsp, api, packaging, session]
---
## Objective
Create the flat-packed `prometeu-lsp` module surfaces and the Studio/VFS session seams required by DEC-0011 before semantic capabilities are implemented.
## Background
`prometeu-lsp` currently exists only as empty Gradle modules.
DEC-0011 requires:
- flat packaging in the style of `prometeu-packer-api`,
- a Studio-integrated semantic consumer above VFS,
- and a clean session-level seam for opened-document snapshots and closed-document filesystem fallback.
## Scope
### Included
- scaffold public LSP API packages and contract types
- scaffold runtime/v1 module shape
- add Studio-side integration seam for a project-session-owned LSP consumer
### Excluded
- actual diagnostics/symbol/definition/highlight logic
- frontend editing
- completion
## Execution Steps
### Step 1 - Create Flat API Surfaces
**What:**
Set up `prometeu-lsp-api` with explicit public package surfaces.
**How:**
Create shallow public packages such as:
- `dtos`
- `messages`
- `events`
along with the top-level service/factory/context contracts needed by Studio.
**File(s):**
- `prometeu-lsp/prometeu-lsp-api/src/main/java/**`
### Step 2 - Create Runtime/V1 Wiring
**What:**
Set up the first concrete implementation module.
**How:**
Add the initial runtime package layout in `prometeu-lsp-v1`, including factory and internal service skeletons that consume `prometeu-vfs` state rather than raw filesystem reads.
**File(s):**
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/**`
- `prometeu-lsp/prometeu-lsp-v1/build.gradle.kts`
### Step 3 - Add Studio Session Integration Seams
**What:**
Make room for a project-session-owned LSP consumer in Studio.
**How:**
Introduce or extend Studio project-session types so an integrated LSP consumer can later be constructed from project context and VFS access without changing the architectural owner.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/projectsessions/**`
- `prometeu-studio/src/main/java/p/studio/window/MainView.java`
- `prometeu-studio/src/main/java/p/studio/window/StudioWindowCoordinator.java`
## Test Requirements
### Unit Tests
- API contract smoke tests where useful
- session-seam construction tests
### Integration Tests
- project-session integration test proving Studio can construct LSP scaffold without semantic behavior yet
### Manual Verification
- confirm package layout is shallow and public surfaces are legible
- confirm no direct filesystem ownership leaks into Studio UI code
## Acceptance Criteria
- [ ] `prometeu-lsp-api` exposes flat public package surfaces
- [ ] `prometeu-lsp-v1` contains concrete scaffold wiring above VFS
- [ ] Studio has a session seam ready for an integrated LSP consumer
- [ ] no semantic feature implementation is required yet for the scaffold to compile
## Dependencies
- DEC-0011 accepted
- PLN-0022 review completed or otherwise stable enough for contract shape
- DEC-0010 major VFS contract direction already stable
## Risks
- public API may accidentally mirror internal implementation packages too closely
- Studio session ownership could drift if LSP is wired too low in the editor UI
- premature semantic helpers may leak into the scaffold plan if scope is not kept tight

120
discussion/workflow/plans/PLN-0024-implement-read-only-fe-diagnostics-symbols-and-definition.md
View File

@ -1,120 +0,0 @@
---
id: PLN-0024
ticket: studio-editor-write-wave-supported-non-frontend-files
title: Implement read-only FE diagnostics, symbols, and definition over VFS snapshots
status: done
created: 2026-03-31
completed: 2026-03-31
tags: [studio, lsp, diagnostics, symbols, definition, frontend]
---
## Objective
Implement the non-highlight semantic capabilities of DEC-0011 for read-only frontend documents by consuming VFS snapshots through the integrated LSP seam.
## Background
DEC-0011 defines a minimum semantic-read phase for FE documents.
This plan focuses on the analysis-driven capabilities that do not depend on frontend highlight/color delivery:
- diagnostics,
- symbols/outline,
- and definition.
The compiler pipeline already exposes `analyze` as a no-write semantic entrypoint suitable for tooling.
## Scope
### Included
- diagnostics for FE documents
- symbol/outline data for FE documents
- definition for FE documents
- VFS-snapshot-backed analysis for open docs and filesystem fallback for closed docs
### Excluded
- frontend highlight
- completion
- frontend editing
## Execution Steps
### Step 1 - Build Analysis Snapshot Ingestion
**What:**
Connect the integrated LSP runtime to the compiler `analyze` pipeline over VFS-provided document state.
**How:**
Implement the runtime path that:
- reads open-document snapshot state from VFS,
- falls back to filesystem-backed state for closed docs,
- produces analysis snapshots,
- and keeps build-side persistence out of scope.
**File(s):**
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/**`
- `prometeu-compiler/prometeu-build-pipeline/**` callsites as needed
### Step 2 - Expose Diagnostics
**What:**
Surface FE diagnostics through the integrated LSP contracts.
**How:**
Map analysis results into LSP-facing DTOs/messages and ensure Studio consumers can receive them without requiring frontend editing.
**File(s):**
- `prometeu-lsp/prometeu-lsp-api/src/main/java/**`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/**`
### Step 3 - Expose Symbols, Outline, and Definition
**What:**
Provide enough semantic structure for FE read-only navigation.
**How:**
Use analysis facts to expose:
- document symbols,
- workspace symbols,
- outline-facing structure,
- go-to-definition.
**File(s):**
- `prometeu-lsp/prometeu-lsp-api/src/main/java/**`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/**`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorOutlinePanel.java`
## Test Requirements
### Unit Tests
- analysis snapshot ingestion from open and closed document sources
- diagnostics mapping
- symbol/definition mapping
### Integration Tests
- end-to-end FE semantic-read test over a project-session VFS snapshot
### Manual Verification
- open FE docs and confirm diagnostics appear
- confirm outline/symbol navigation works without unlocking editing
- confirm definition resolves from open in-memory docs
## Acceptance Criteria
- [ ] FE diagnostics work from VFS-backed analysis
- [ ] FE symbols and outline data are available in read-only mode
- [ ] go-to-definition works against the same semantic substrate
- [ ] open docs use in-memory snapshot state while closed docs can use filesystem fallback
## Dependencies
- DEC-0011 accepted
- PLN-0023 review completed or otherwise stable enough to provide runtime seams
- DEC-0010/editor-session substrate major pieces sufficiently stable
## Risks
- analysis ingestion may accidentally bypass VFS and read files directly
- outline/symbol shape may drift if not modeled cleanly in API contracts
- definition support may require compiler facts not yet surfaced cleanly

108
discussion/workflow/plans/PLN-0025-implement-fe-semantic-highlight-consumption.md
View File

@ -1,108 +0,0 @@
---
id: PLN-0025
ticket: studio-editor-write-wave-supported-non-frontend-files
title: Implement FE semantic highlight and editor consumption for the read-only LSP phase
status: done
created: 2026-03-31
completed: 2026-03-31
tags: [studio, lsp, highlight, frontend, editor]
---
## Objective
Implement frontend highlight delivery through `prometeu-lsp` semantics while leaving non-frontend highlighting Studio-local as DEC-0011 requires.
## Background
DEC-0011 explicitly separates highlight ownership:
- non-frontend highlight may remain local to the Studio editor,
- frontend highlight must come from the integrated LSP semantic layer and frontend-owned color semantics.
This deserves its own plan because it crosses API, runtime, and editor presentation boundaries.
## Scope
### Included
- FE semantic highlight contracts in LSP
- FE semantic highlight production in runtime
- editor consumption path for FE highlight
- frontend-owned color semantics integration
### Excluded
- non-frontend highlight rewrite
- completion
- frontend editing
## Execution Steps
### Step 1 - Define FE Highlight Contracts
**What:**
Add LSP-facing contracts for semantic highlight delivery.
**How:**
Define DTOs/messages that carry FE semantic highlight spans and any required theme/color semantics without forcing Studio-local token rules onto FE documents.
**File(s):**
- `prometeu-lsp/prometeu-lsp-api/src/main/java/**`
### Step 2 - Implement Runtime Highlight Production
**What:**
Produce FE highlight data from the integrated LSP runtime.
**How:**
Implement the runtime path that derives semantic highlight facts for FE docs from the same read-only analysis substrate used by diagnostics and symbols.
**File(s):**
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/**`
### Step 3 - Consume FE Highlight in the Editor
**What:**
Make the editor choose FE highlight from LSP while leaving other document types on the existing local path.
**How:**
Update editor presentation routing so:
- FE docs use LSP semantic highlight results and frontend-owned color semantics,
- non-FE docs continue using Studio-local highlighting.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentPresentationRegistry.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/syntaxhighlight/**`
- `prometeu-studio/src/main/resources/themes/editor/**`
## Test Requirements
### Unit Tests
- FE highlight DTO/runtime mapping
- editor routing between FE LSP highlight and non-FE local highlight
### Integration Tests
- FE document read-only semantic highlight test through Studio + VFS + LSP path
### Manual Verification
- open FE docs and confirm semantic highlight comes from LSP-driven data
- open non-FE docs and confirm existing local highlighting still works
## Acceptance Criteria
- [ ] FE highlight is produced by the integrated LSP runtime
- [ ] FE highlight uses frontend-owned color semantics rather than Studio-local fallback token rules
- [ ] non-FE highlighting remains on the existing local Studio path
- [ ] editor presentation routing clearly separates FE and non-FE highlight ownership
## Dependencies
- DEC-0011 accepted
- PLN-0023 review completed or otherwise stable enough for LSP contracts/runtime
- PLN-0024 review completed or otherwise stable enough to provide shared FE semantic facts
## Risks
- FE highlight could accidentally duplicate or conflict with local Studio token rules
- color-semantics contracts may become too UI-coupled if not modeled carefully
- editor routing may become fragile if FE and non-FE ownership boundaries are not explicit

113
discussion/workflow/plans/PLN-0026-propagate-dec-0012-into-studio-and-frontend-specs.md
View File

@ -1,113 +0,0 @@
---
id: PLN-0026
ticket: studio-frontend-owned-semantic-editor-presentation
title: Propagate DEC-0012 into Studio and frontend normative specs
status: review
created: 2026-04-02
completed:
tags:
- studio
- editor
- frontend
- specs
- semantic-highlighting
---
## Objective
Propagate `DEC-0012` into the normative documentation surfaces that define semantic editor presentation ownership, contract source, and runtime fallback behavior.
## Background
`DEC-0012` locks a new ownership model:
- frontend owns semantic vocabulary;
- frontend owns semantic presentation resources;
- `FrontendSpec` is the canonical source of the semantic presentation contract;
- LSP derives a descriptor from `FrontendSpec`;
- Studio consumes the descriptor without semantic reinterpretation;
- missing descriptor or resources degrade to no semantic highlight.
These rules must be reflected in the Studio and frontend-facing specs before implementation work proceeds.
## Scope
### Included
- Studio editor specification updates for frontend-owned semantic presentation.
- LSP semantic read phase specification updates for descriptor bridging behavior.
- Compiler/frontend specification updates that place semantic presentation contract ownership in `FrontendSpec`.
- Documentation of the runtime behavior `no contract/resource -> no highlight`.
### Excluded
- Java implementation changes.
- FE resource creation or stylesheet migration.
- Test implementation.
## Execution Steps
### Step 1 - Update Studio semantic editor ownership rules
**What:**
Update Studio specs so the editor is no longer the owner of a generic frontend semantic theme.
**How:**
Amend the Code Editor and related Studio specs to state that Studio hosts rendering only, consumes a frontend-owned descriptor, and applies no generic fallback theme.
**File(s):**
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
### Step 2 - Update frontend contract ownership rules
**What:**
Document that frontend semantic presentation contract data lives in `FrontendSpec`.
**How:**
Amend compiler/frontend spec surfaces to describe `semanticKeys + resources` as frontend-owned static contract data published through `FrontendSpec`.
**File(s):**
- `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md`
- `docs/specs/compiler-languages/pbs/README.md`
- any more specific frontend spec file that currently owns frontend metadata publication semantics
### Step 3 - Lock runtime degradation behavior in spec text
**What:**
Specify the runtime behavior when semantic presentation contract data or resources are absent.
**How:**
State normatively that Studio must continue without semantic highlight, must not surface a product-facing UI error, and may only emit normal development logs.
**File(s):**
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
## Test Requirements
### Unit Tests
- No code tests in this plan.
### Integration Tests
- No runtime tests in this plan.
### Manual Verification
- Review updated spec text against every normative clause in `DEC-0012`.
- Verify no spec reintroduces a Studio-owned generic frontend theme.
## Acceptance Criteria
- [ ] Studio specs state that semantic presentation is frontend-owned.
- [ ] Specs name `FrontendSpec` as the canonical contract source.
- [ ] Specs describe the descriptor shape at a high level as `semanticKeys + resources`.
- [ ] Specs define `no contract/resource -> no highlight`.
- [ ] Specs define that no generic Studio fallback theme is allowed.
## Dependencies
- Depends on `DEC-0012`.
- Should complete before or in parallel with implementation plans so implementation follows normative text.
## Risks
- Existing spec text may still imply Studio ownership of generic frontend presentation.
- Compiler spec propagation may be underspecified if the exact frontend metadata sections are spread across multiple files.

139
discussion/workflow/plans/PLN-0027-add-frontend-semantic-presentation-contract-and-lsp-descriptor.md
View File

@ -1,139 +0,0 @@
---
id: PLN-0027
ticket: studio-frontend-owned-semantic-editor-presentation
title: Add frontend semantic presentation contract to FrontendSpec and expose it through LSP
status: review
created: 2026-04-02
completed:
tags:
- compiler
- frontend
- lsp
- contract
- semantic-highlighting
---
## Objective
Implement the frontend-owned semantic presentation contract in `FrontendSpec` and expose a derived descriptor through LSP without collapsing frontend semantics into host-owned categories.
## Background
`DEC-0012` requires:
- static contract data in `FrontendSpec`;
- a simple descriptor containing `semanticKeys + resources`;
- frontend-owned semantic vocabulary using stable `semanticKey` values;
- LSP as a hub that derives and exposes the descriptor to Studio;
- no generic semantic-key reduction such as `fe-keyword`.
## Scope
### Included
- `FrontendSpec` contract model additions.
- FE-specific publication of semantic keys and semantic presentation resources.
- Replacement of generic LSP semantic key emission with frontend-owned keys.
- LSP descriptor derivation and API exposure.
- FE-side tests covering contract presence and consistency.
### Excluded
- Studio CSS application changes.
- Studio presentation registry migration.
- Removal of legacy Studio stylesheets, except where required to avoid compile/runtime conflicts.
## Execution Steps
### Step 1 - Extend FrontendSpec with semantic presentation contract
**What:**
Add a static semantic presentation contract to `FrontendSpec`.
**How:**
Introduce a dedicated descriptor type that carries frontend-owned `semanticKeys + resources`, wire it into `FrontendSpec`, and keep `FrontendSpec` static and frontend-owned.
**File(s):**
- `prometeu-compiler/prometeu-frontend-api/src/main/java/.../FrontendSpec.java`
- any adjacent model files needed for the new descriptor type
### Step 2 - Publish PBS semantic vocabulary and resources through FrontendSpec
**What:**
Make PBS publish frontend-owned semantic keys and highlight resources.
**How:**
Add a frontend-owned semantic vocabulary model such as `PbsSemanticKind -> semanticKey`, publish the resulting semantic presentation contract from PBS frontend definitions, and point the descriptor to FE-owned resources.
**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSDefinitions.java`
- PBS semantic analysis/indexing files that currently assign generic `fe-*` categories
- FE resource directory under the PBS frontend module
### Step 3 - Remove generic semantic key collapse in LSP
**What:**
Stop translating frontend semantics into host-owned generic semantic keys.
**How:**
Replace `fe-keyword`, `fe-type`, and similar outputs with frontend-owned semantic keys coming from frontend semantic vocabulary and/or `FrontendSpec` contract data.
**File(s):**
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/models/SemanticIndex.java`
- any LSP DTO/message models that need to surface the descriptor
### Step 4 - Expose descriptor from analysis to Studio-facing LSP results
**What:**
Expose a Studio-consumable descriptor derived from the resolved `FrontendSpec`.
**How:**
Derive the descriptor during analysis/session creation and include it in the LSP surface that Studio consumes for semantic highlight application.
**File(s):**
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspSemanticReadPhase.java`
- `prometeu-lsp/prometeu-lsp-api/src/main/java/...` messages/DTOs
- any semantic session models involved in transport
### Step 5 - Add FE contract tests
**What:**
Verify the FE contract is present and coherent.
**How:**
Add frontend tests that fail when semantic presentation contract data is missing, when semantic keys are not published, or when published resources do not match the FE contract shape expectations.
**File(s):**
- PBS frontend tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/...`
- frontend-api tests if `FrontendSpec` invariants are enforced there
## Test Requirements
### Unit Tests
- `FrontendSpec` tests for semantic presentation descriptor presence and shape.
- PBS frontend tests for semantic key publication.
- LSP tests for transport of frontend-owned semantic keys and descriptor data.
### Integration Tests
- Analyze a PBS file through LSP and assert that returned semantic highlights use PBS-owned semantic keys.
- Assert that the descriptor surfaced to the consumer contains the expected `semanticKeys + resources`.
### Manual Verification
- Inspect LSP payloads/logs to confirm there is no remaining `fe-*` semantic key collapse for PBS.
## Acceptance Criteria
- [ ] `FrontendSpec` exposes a static semantic presentation contract.
- [ ] PBS publishes semantic keys and resources through that contract.
- [ ] LSP no longer emits generic host-owned semantic keys for PBS.
- [ ] LSP exposes a descriptor derived from resolved `FrontendSpec`.
- [ ] FE tests cover missing contract data and contract consistency.
## Dependencies
- Depends on `DEC-0012`.
- Should land before Studio consumption changes in `PLN-0028`.
## Risks
- Existing semantic indexing code is currently host-owned and may require a larger refactor than expected.
- DTO surface changes can ripple through Studio and tests.
- Resource publication conventions may be inconsistent across future frontends if not modeled cleanly now.

132
discussion/workflow/plans/PLN-0028-consume-frontend-owned-semantic-presentation-in-studio.md
View File

@ -1,132 +0,0 @@
---
id: PLN-0028
ticket: studio-frontend-owned-semantic-editor-presentation
title: Consume frontend-owned semantic presentation in Studio and retire generic FE theme usage
status: review
created: 2026-04-02
completed:
tags:
- studio
- editor
- semantic-highlighting
- frontend
- presentation
---
## Objective
Make Studio consume the frontend-owned semantic presentation descriptor from LSP, apply FE-owned resources, and degrade cleanly to no highlight when semantic presentation data is unavailable.
## Background
`DEC-0012` and `PLN-0027` move semantic presentation ownership out of Studio. After the descriptor and frontend resources exist, Studio must stop relying on generic frontend presentation styling and instead consume FE-owned semantic presentation data.
## Scope
### Included
- Studio-side consumption of the LSP semantic presentation descriptor.
- Mechanical semantic key to CSS class projection.
- Loading FE-owned highlight resources through normal Java resource resolution.
- Graceful no-highlight behavior when descriptor/resources are unavailable.
- Removal of generic FE-specific highlight ownership assumptions from Studio runtime flow.
### Excluded
- Frontend contract creation.
- LSP descriptor creation.
- Spec writing.
## Execution Steps
### Step 1 - Add descriptor-aware Studio highlight consumption
**What:**
Teach Studio editor highlighting flow to consume the frontend semantic presentation descriptor.
**How:**
Extend the Studio-side LSP consumption path so semantic highlight application depends on descriptor data and no longer assumes a single generic frontend presentation.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentPresentationRegistry.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/syntaxhighlight/EditorDocumentSemanticHighlighting.java`
### Step 2 - Replace generic FE styling assumption with mechanical class projection
**What:**
Project frontend semantic keys directly into CSS classes.
**How:**
Implement a stable Studio-side projection rule such as `semanticKey -> editor-semantic-<semanticKey>` and apply those classes to semantic spans without any semantic translation layer.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/syntaxhighlight/EditorDocumentSemanticHighlighting.java`
- any adjacent presentation/style support files
### Step 3 - Load FE-owned resources and remove generic FE ownership path
**What:**
Load FE-owned stylesheet resources rather than Studio-owned generic FE semantic CSS.
**How:**
Use descriptor resources surfaced through LSP, attach the referenced stylesheet(s) to the editor presentation/runtime flow, and stop depending on generic `fe.css` as the semantic owner for FE documents.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentPresentationRegistry.java`
- `prometeu-studio/src/main/resources/themes/editor/presentations/fe.css` if retired or narrowed
### Step 4 - Implement graceful no-highlight degradation
**What:**
Ensure Studio continues to work without semantic highlight when descriptor/resources are absent.
**How:**
When the descriptor is absent or resources cannot be consumed, skip semantic styling for that frontend document, preserve editor usability, and avoid user-facing Studio errors.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
- semantic highlight routing/presentation files in the editor workspace
### Step 5 - Add Studio tests for FE-owned semantic presentation consumption
**What:**
Cover descriptor consumption, class projection, and no-highlight degradation.
**How:**
Add editor-side tests that assert Studio consumes descriptor data, applies projected classes, and keeps operating when descriptor/resources are missing.
**File(s):**
- `prometeu-studio/src/test/java/p/studio/workspaces/editor/...`
## Test Requirements
### Unit Tests
- Editor highlight routing tests for semantic key projection.
- Presentation registry tests for descriptor-driven resource loading.
- No-highlight degradation tests when descriptor/resources are absent.
### Integration Tests
- End-to-end Studio/LSP test using a frontend document with FE-owned semantic keys and FE-owned stylesheet resources.
### Manual Verification
- Open a PBS document and verify semantic colors come from FE-owned presentation resources, not generic Studio FE theme assumptions.
- Temporarily remove or break the descriptor/resource and verify the editor remains usable with no semantic highlight.
## Acceptance Criteria
- [ ] Studio consumes frontend-owned semantic presentation descriptor data from LSP.
- [ ] Studio projects semantic keys mechanically to CSS classes.
- [ ] Generic Studio-owned frontend semantic presentation is no longer the runtime owner for FE highlight.
- [ ] Missing descriptor/resources degrade to no highlight without Studio UI errors.
- [ ] Studio tests cover the new descriptor consumption path.
## Dependencies
- Depends on `DEC-0012`.
- Depends on `PLN-0027` for descriptor and resource publication.
- Can run after or in parallel with `PLN-0026`, but should not merge before the contract surface in `PLN-0027` exists.
## Risks
- Existing Studio presentation registry may assume static local stylesheets and need a broader refactor.
- Descriptor-driven resource loading can accidentally leak stylesheet accumulation if lifecycle cleanup is not handled carefully.
- Partial migration may leave residual `fe.css` assumptions in tests or runtime paths.