diff --git a/discussion/.backups/index.ndjson.20260327-161618.bak b/discussion/.backups/index.ndjson.20260402-170740.bak similarity index 51% rename from discussion/.backups/index.ndjson.20260327-161618.bak rename to discussion/.backups/index.ndjson.20260402-170740.bak index 6c284e9f..7ac22b0e 100644 --- a/discussion/.backups/index.ndjson.20260327-161618.bak +++ b/discussion/.backups/index.ndjson.20260402-170740.bak @@ -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":[]} diff --git a/discussion/.backups/index.ndjson.20260327-165050.bak b/discussion/.backups/index.ndjson.20260402-171350.bak similarity index 61% rename from discussion/.backups/index.ndjson.20260327-165050.bak rename to discussion/.backups/index.ndjson.20260402-171350.bak index bf4f5ae1..f0484296 100644 --- a/discussion/.backups/index.ndjson.20260327-165050.bak +++ b/discussion/.backups/index.ndjson.20260402-171350.bak @@ -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":[]} diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 7ac22b0e..534d27b7 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -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"}]} diff --git a/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 b/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 new file mode 100644 index 00000000..5d1af977 --- /dev/null +++ b/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 @@ -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. diff --git a/discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md b/discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md new file mode 100644 index 00000000..08b8eaaa --- /dev/null +++ b/discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md @@ -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. diff --git a/discussion/workflow/agendas/AGD-0013-studio-editor-write-wave-supported-non-frontend-files.md b/discussion/workflow/agendas/AGD-0013-studio-editor-write-wave-supported-non-frontend-files.md deleted file mode 100644 index c1adee58..00000000 --- a/discussion/workflow/agendas/AGD-0013-studio-editor-write-wave-supported-non-frontend-files.md +++ /dev/null @@ -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. diff --git a/discussion/workflow/agendas/AGD-0014-studio-editor-frontend-edit-rights.md b/discussion/workflow/agendas/AGD-0014-studio-editor-frontend-edit-rights.md deleted file mode 100644 index 52eaaa5e..00000000 --- a/discussion/workflow/agendas/AGD-0014-studio-editor-frontend-edit-rights.md +++ /dev/null @@ -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. diff --git a/discussion/workflow/agendas/AGD-0015-studio-frontend-owned-semantic-editor-presentation.md b/discussion/workflow/agendas/AGD-0015-studio-frontend-owned-semantic-editor-presentation.md deleted file mode 100644 index 6b7ab83b..00000000 --- a/discussion/workflow/agendas/AGD-0015-studio-frontend-owned-semantic-editor-presentation.md +++ /dev/null @@ -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/`. - -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/` 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/`. - -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". diff --git a/discussion/workflow/decisions/DEC-0010-studio-controlled-non-frontend-editor-write-wave.md b/discussion/workflow/decisions/DEC-0010-studio-controlled-non-frontend-editor-write-wave.md deleted file mode 100644 index db969ef2..00000000 --- a/discussion/workflow/decisions/DEC-0010-studio-controlled-non-frontend-editor-write-wave.md +++ /dev/null @@ -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. diff --git a/discussion/workflow/decisions/DEC-0011-studio-frontend-read-only-minimum-lsp-phase.md b/discussion/workflow/decisions/DEC-0011-studio-frontend-read-only-minimum-lsp-phase.md deleted file mode 100644 index 1042af1a..00000000 --- a/discussion/workflow/decisions/DEC-0011-studio-frontend-read-only-minimum-lsp-phase.md +++ /dev/null @@ -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. diff --git a/discussion/workflow/decisions/DEC-0012-frontend-owned-semantic-editor-presentation.md b/discussion/workflow/decisions/DEC-0012-frontend-owned-semantic-editor-presentation.md deleted file mode 100644 index 602ac7f5..00000000 --- a/discussion/workflow/decisions/DEC-0012-frontend-owned-semantic-editor-presentation.md +++ /dev/null @@ -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. diff --git a/discussion/workflow/plans/PLN-0019-propagate-dec-0010-into-studio-and-vfs-specs.md b/discussion/workflow/plans/PLN-0019-propagate-dec-0010-into-studio-and-vfs-specs.md deleted file mode 100644 index d9d48420..00000000 --- a/discussion/workflow/plans/PLN-0019-propagate-dec-0010-into-studio-and-vfs-specs.md +++ /dev/null @@ -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 diff --git a/discussion/workflow/plans/PLN-0020-build-dec-0010-vfs-access-policy-and-save-core.md b/discussion/workflow/plans/PLN-0020-build-dec-0010-vfs-access-policy-and-save-core.md deleted file mode 100644 index 15c129ef..00000000 --- a/discussion/workflow/plans/PLN-0020-build-dec-0010-vfs-access-policy-and-save-core.md +++ /dev/null @@ -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 diff --git a/discussion/workflow/plans/PLN-0021-integrate-dec-0010-editor-write-ui-and-workflow.md b/discussion/workflow/plans/PLN-0021-integrate-dec-0010-editor-write-ui-and-workflow.md deleted file mode 100644 index 78c30fbf..00000000 --- a/discussion/workflow/plans/PLN-0021-integrate-dec-0010-editor-write-ui-and-workflow.md +++ /dev/null @@ -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 diff --git a/discussion/workflow/plans/PLN-0022-propagate-dec-0011-into-studio-vfs-and-lsp-specs.md b/discussion/workflow/plans/PLN-0022-propagate-dec-0011-into-studio-vfs-and-lsp-specs.md deleted file mode 100644 index 4e5e8637..00000000 --- a/discussion/workflow/plans/PLN-0022-propagate-dec-0011-into-studio-vfs-and-lsp-specs.md +++ /dev/null @@ -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 diff --git a/discussion/workflow/plans/PLN-0023-scaffold-flat-packed-prometeu-lsp-api-and-session-seams.md b/discussion/workflow/plans/PLN-0023-scaffold-flat-packed-prometeu-lsp-api-and-session-seams.md deleted file mode 100644 index 8ae9c2cb..00000000 --- a/discussion/workflow/plans/PLN-0023-scaffold-flat-packed-prometeu-lsp-api-and-session-seams.md +++ /dev/null @@ -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 diff --git a/discussion/workflow/plans/PLN-0024-implement-read-only-fe-diagnostics-symbols-and-definition.md b/discussion/workflow/plans/PLN-0024-implement-read-only-fe-diagnostics-symbols-and-definition.md deleted file mode 100644 index 77429ebb..00000000 --- a/discussion/workflow/plans/PLN-0024-implement-read-only-fe-diagnostics-symbols-and-definition.md +++ /dev/null @@ -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 diff --git a/discussion/workflow/plans/PLN-0025-implement-fe-semantic-highlight-consumption.md b/discussion/workflow/plans/PLN-0025-implement-fe-semantic-highlight-consumption.md deleted file mode 100644 index ad976063..00000000 --- a/discussion/workflow/plans/PLN-0025-implement-fe-semantic-highlight-consumption.md +++ /dev/null @@ -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 diff --git a/discussion/workflow/plans/PLN-0026-propagate-dec-0012-into-studio-and-frontend-specs.md b/discussion/workflow/plans/PLN-0026-propagate-dec-0012-into-studio-and-frontend-specs.md deleted file mode 100644 index 3f01c6e6..00000000 --- a/discussion/workflow/plans/PLN-0026-propagate-dec-0012-into-studio-and-frontend-specs.md +++ /dev/null @@ -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. diff --git a/discussion/workflow/plans/PLN-0027-add-frontend-semantic-presentation-contract-and-lsp-descriptor.md b/discussion/workflow/plans/PLN-0027-add-frontend-semantic-presentation-contract-and-lsp-descriptor.md deleted file mode 100644 index 9fd066bc..00000000 --- a/discussion/workflow/plans/PLN-0027-add-frontend-semantic-presentation-contract-and-lsp-descriptor.md +++ /dev/null @@ -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. diff --git a/discussion/workflow/plans/PLN-0028-consume-frontend-owned-semantic-presentation-in-studio.md b/discussion/workflow/plans/PLN-0028-consume-frontend-owned-semantic-presentation-in-studio.md deleted file mode 100644 index 7a8fc1cd..00000000 --- a/discussion/workflow/plans/PLN-0028-consume-frontend-owned-semantic-presentation-in-studio.md +++ /dev/null @@ -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-` 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.