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

housekeep

Browse Source
This commit is contained in:
bQUARKz 2026-04-06 04:39:27 +01:00
parent 770aa6a387
commit 5871243f8f
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
19 changed files with 390 additions and 1790 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
discussion/.backups/index.ndjson.20260330-205742.bak → discussion/.backups/index.ndjson.20260406-043719.bak
View File

@ -1,4 +1,4 @@
{"type":"meta","next_id":{"DSC":12,"AGD":12,"DEC":8,"PLN":12,"LSN":26,"CLSN":1}}
{"type":"meta","next_id":{"DSC":22,"AGD":23,"DEC":20,"PLN":41,"LSN":34,"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"}]}
@ -8,5 +8,15 @@
{"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":"open","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-30","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[{"id":"AGD-0010","file":"AGD-0010-studio-code-editor-workspace-foundations.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":"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"}]}
{"type":"discussion","id":"DSC-0015","status":"done","ticket":"pbs-service-facade-reserved-metadata","title":"SDK Service Bodies Calling Builtin/Intrinsic Proxies as Ordinary PBS Code","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["compiler","pbs","sdk","stdlib","lowering","service","intrinsic","sdk-interface"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"discussion/lessons/DSC-0015-pbs-service-facade-reserved-metadata/LSN-0030-sdk-service-bodies-over-private-reserved-proxies.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}]}
{"type":"discussion","id":"DSC-0016","status":"open","ticket":"studio-editor-scope-guides-and-brace-anchoring","title":"Scope Guides do Code Editor com ancoragem exata em braces e destaque do escopo ativo","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","scope-guides","braces","semantic-read","frontend-contract"],"agendas":[{"id":"AGD-0017","file":"AGD-0017-studio-editor-scope-guides-and-brace-anchoring.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0014","file":"DEC-0014-studio-editor-active-scope-and-structural-anchors.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"plans":[{"id":"PLN-0030","file":"PLN-0030-studio-active-container-and-active-scope-gutter-wave-1.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0031","file":"PLN-0031-studio-structural-anchor-semantic-surface-specification.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0032","file":"PLN-0032-frontend-structural-anchor-payloads-and-anchor-aware-tests.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}],"lessons":[]}
{"type":"discussion","id":"DSC-0017","status":"open","ticket":"studio-editor-inline-type-hints-for-let-bindings","title":"Inline Type Hints for Let Bindings in the Studio Editor","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","inline-hints","inlay-hints","lsp","pbs","type-inference"],"agendas":[{"id":"AGD-0018","file":"AGD-0018-studio-editor-inline-type-hints-for-let-bindings.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0015","file":"DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03","ref_agenda":"AGD-0018"}],"plans":[{"id":"PLN-0033","file":"PLN-0033-inline-hint-spec-and-contract-propagation.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0034","file":"PLN-0034-lsp-inline-hint-transport-contract.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0035","file":"PLN-0035-pbs-inline-type-hint-payload-production.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0036","file":"PLN-0036-studio-inline-hint-rendering-and-rollout.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0018","status":"done","ticket":"studio-project-local-studio-state-under-dot-studio","title":"Persist project-local Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","shell","layout","setup"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0031","file":"discussion/lessons/DSC-0018-studio-project-local-studio-state-under-dot-studio/LSN-0031-project-local-studio-state-and-lifecycle-safe-layout-restoration.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"studio-project-local-setup-separate-from-main-studio-state","title":"Separate project-local setup from the main Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","setup","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0032","file":"discussion/lessons/DSC-0019-studio-project-local-setup-separate-from-main-studio-state/LSN-0032-separate-project-config-from-session-restoration-state.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"studio-editor-indentation-policy-and-project-setup","title":"Indentation Policy, Status-Bar Semantics, and Project-Local Editor Setup","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","editor","indentation","tabs","setup","dot-studio","configuration","ux"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0033","file":"discussion/lessons/DSC-0020-studio-editor-indentation-policy-and-project-setup/LSN-0033-setup-owned-indentation-policy-and-project-bootstrap-defaults.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
{"type":"discussion","id":"DSC-0021","status":"open","ticket":"studio-frontend-editor-write-and-save-wave","title":"Enable Frontend Editing and Save in the Studio Code Editor","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","editor","frontend","write","save","vfs","lsp","pbs","access-policy"],"agendas":[{"id":"AGD-0022","file":"AGD-0022-studio-frontend-editor-write-and-save-wave.md","status":"accepted","created_at":"2026-04-04","updated_at":"2026-04-04"}],"decisions":[{"id":"DEC-0019","file":"DEC-0019-studio-frontend-editor-write-and-save-wave.md","status":"accepted","created_at":"2026-04-04","updated_at":"2026-04-04","ref_agenda":"AGD-0022"}],"plans":[{"id":"PLN-0040","file":"PLN-0040-studio-frontend-editor-write-and-save-wave.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04","ref_decisions":["DEC-0019"]}],"lessons":[]}

8
discussion/index.ndjson
View File

@ -1,4 +1,4 @@
{"type":"meta","next_id":{"DSC":22,"AGD":23,"DEC":20,"PLN":41,"LSN":34,"CLSN":1}}
{"type":"meta","next_id":{"DSC":22,"AGD":23,"DEC":20,"PLN":41,"LSN":37,"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"}]}
@ -14,9 +14,9 @@
{"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"}]}
{"type":"discussion","id":"DSC-0015","status":"done","ticket":"pbs-service-facade-reserved-metadata","title":"SDK Service Bodies Calling Builtin/Intrinsic Proxies as Ordinary PBS Code","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["compiler","pbs","sdk","stdlib","lowering","service","intrinsic","sdk-interface"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"discussion/lessons/DSC-0015-pbs-service-facade-reserved-metadata/LSN-0030-sdk-service-bodies-over-private-reserved-proxies.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}]}
{"type":"discussion","id":"DSC-0016","status":"open","ticket":"studio-editor-scope-guides-and-brace-anchoring","title":"Scope Guides do Code Editor com ancoragem exata em braces e destaque do escopo ativo","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","scope-guides","braces","semantic-read","frontend-contract"],"agendas":[{"id":"AGD-0017","file":"AGD-0017-studio-editor-scope-guides-and-brace-anchoring.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0014","file":"DEC-0014-studio-editor-active-scope-and-structural-anchors.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"plans":[{"id":"PLN-0030","file":"PLN-0030-studio-active-container-and-active-scope-gutter-wave-1.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0031","file":"PLN-0031-studio-structural-anchor-semantic-surface-specification.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0032","file":"PLN-0032-frontend-structural-anchor-payloads-and-anchor-aware-tests.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}],"lessons":[]}
{"type":"discussion","id":"DSC-0017","status":"open","ticket":"studio-editor-inline-type-hints-for-let-bindings","title":"Inline Type Hints for Let Bindings in the Studio Editor","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","inline-hints","inlay-hints","lsp","pbs","type-inference"],"agendas":[{"id":"AGD-0018","file":"AGD-0018-studio-editor-inline-type-hints-for-let-bindings.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0015","file":"DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03","ref_agenda":"AGD-0018"}],"plans":[{"id":"PLN-0033","file":"PLN-0033-inline-hint-spec-and-contract-propagation.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0034","file":"PLN-0034-lsp-inline-hint-transport-contract.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0035","file":"PLN-0035-pbs-inline-type-hint-payload-production.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0036","file":"PLN-0036-studio-inline-hint-rendering-and-rollout.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0016","status":"done","ticket":"studio-editor-scope-guides-and-brace-anchoring","title":"Scope Guides do Code Editor com ancoragem exata em braces e destaque do escopo ativo","created_at":"2026-04-03","updated_at":"2026-04-06","tags":["studio","editor","scope-guides","braces","semantic-read","frontend-contract"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0034","file":"discussion/lessons/DSC-0016-studio-editor-scope-guides-and-brace-anchoring/LSN-0034-active-scope-gutter-and-frontend-owned-structural-anchors.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
{"type":"discussion","id":"DSC-0017","status":"done","ticket":"studio-editor-inline-type-hints-for-let-bindings","title":"Inline Type Hints for Let Bindings in the Studio Editor","created_at":"2026-04-03","updated_at":"2026-04-06","tags":["studio","editor","inline-hints","inlay-hints","lsp","pbs","type-inference"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0035","file":"discussion/lessons/DSC-0017-studio-editor-inline-type-hints-for-let-bindings/LSN-0035-frontend-owned-inline-hints-with-decorative-inline-rendering.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
{"type":"discussion","id":"DSC-0018","status":"done","ticket":"studio-project-local-studio-state-under-dot-studio","title":"Persist project-local Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","shell","layout","setup"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0031","file":"discussion/lessons/DSC-0018-studio-project-local-studio-state-under-dot-studio/LSN-0031-project-local-studio-state-and-lifecycle-safe-layout-restoration.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"studio-project-local-setup-separate-from-main-studio-state","title":"Separate project-local setup from the main Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","setup","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0032","file":"discussion/lessons/DSC-0019-studio-project-local-setup-separate-from-main-studio-state/LSN-0032-separate-project-config-from-session-restoration-state.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"studio-editor-indentation-policy-and-project-setup","title":"Indentation Policy, Status-Bar Semantics, and Project-Local Editor Setup","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","editor","indentation","tabs","setup","dot-studio","configuration","ux"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0033","file":"discussion/lessons/DSC-0020-studio-editor-indentation-policy-and-project-setup/LSN-0033-setup-owned-indentation-policy-and-project-bootstrap-defaults.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
{"type":"discussion","id":"DSC-0021","status":"open","ticket":"studio-frontend-editor-write-and-save-wave","title":"Enable Frontend Editing and Save in the Studio Code Editor","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","editor","frontend","write","save","vfs","lsp","pbs","access-policy"],"agendas":[{"id":"AGD-0022","file":"AGD-0022-studio-frontend-editor-write-and-save-wave.md","status":"accepted","created_at":"2026-04-04","updated_at":"2026-04-04"}],"decisions":[{"id":"DEC-0019","file":"DEC-0019-studio-frontend-editor-write-and-save-wave.md","status":"accepted","created_at":"2026-04-04","updated_at":"2026-04-04","ref_agenda":"AGD-0022"}],"plans":[{"id":"PLN-0040","file":"PLN-0040-studio-frontend-editor-write-and-save-wave.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04","ref_decisions":["DEC-0019"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"studio-frontend-editor-write-and-save-wave","title":"Enable Frontend Editing and Save in the Studio Code Editor","created_at":"2026-04-04","updated_at":"2026-04-06","tags":["studio","editor","frontend","write","save","vfs","lsp","pbs","access-policy"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0036","file":"discussion/lessons/DSC-0021-studio-frontend-editor-write-and-save-wave/LSN-0036-vfs-owned-frontend-edit-and-save-wave.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}

129
discussion/lessons/DSC-0016-studio-editor-scope-guides-and-brace-anchoring/LSN-0034-active-scope-gutter-and-frontend-owned-structural-anchors.md Normal file
View File

@ -0,0 +1,129 @@
---
id: LSN-0034
ticket: studio-editor-scope-guides-and-brace-anchoring
title: Active-Scope Gutter and Frontend-Owned Structural Anchors
created: 2026-04-06
tags: [studio, editor, scope-guides, structural-anchors, semantic-read, frontend-contract]
---
## Context
The Studio editor already exposed structural guides in the gutter, but the old behavior mixed two different concerns:
- active-scope context in the editor UI,
- and exact structural start/end anchoring.
That combination caused two failures at once:
- the default gutter became visually noisy because it rendered a stacked ancestry map,
- and the guide geometry still depended on approximate local heuristics rather than on language-owned structural metadata.
This discussion split those concerns into a simpler first-wave editor behavior plus a stable long-term semantic contract.
## Key Decisions
### Limit the Default Gutter to `activeScope` and `activeContainer`
**What:**
The default editor gutter now renders at most two active structural indicators:
- `activeScope`, defined as the smallest structural range containing the caret;
- `activeContainer`, defined as the immediate structural ancestor of `activeScope`.
**Why:**
The stacked ancestry gutter produced too much visual noise for routine editing.
The editor needs the nearest structure context, not the whole ancestry map.
**Trade-offs:**
The first wave intentionally drops persistent visibility of higher ancestors.
That loses some ambient hierarchy, but it produces a much clearer default editing signal.
### Keep Exact Anchoring Frontend-Owned Through a Dedicated Semantic Surface
**What:**
Exact guide start and end positions now belong to a dedicated structural-anchor semantic surface rather than to `documentSymbols` or Studio-local text scanning.
**Why:**
Outline/navigation structure and guide geometry are different contracts.
Exact anchoring must survive languages with braces, keywords, indentation, or mixed delimiter schemes, so the final source of truth has to be frontend-owned and language-agnostic.
**Trade-offs:**
The transport and DTO surface become richer, and Studio must consume one more semantic payload.
That cost is worth it because it prevents brace-specific heuristics from becoming the canonical editor contract.
### Keep Presentation Ownership Out of the Core Contract
**What:**
The contract distinguishes semantic roles such as `activeContainer` and `activeScope`, but concrete styling remains frontend-owned.
**Why:**
The host should know which guide is which, but it should not freeze colors, strokes, or theme details into the semantic decision.
**Trade-offs:**
Presentation choices remain distributed across frontend or theme layers.
That is preferable to coupling semantic meaning to one hardcoded Studio style.
## Final Implementation
The final implementation landed across editor behavior, semantic transport, and specs:
- `EditorDocumentScopeGuideModel` now resolves `activeScope` as the smallest containing range and `activeContainer` as the immediate parent, with structural-anchor-aware construction when that metadata is available.
- `EditorWorkspace` recomputes active guide state from caret movement and prefers transported structural anchors over approximate local ranges when the analyze result includes them.
- `EditorDocumentScopeGuideGraphicFactory` renders the constrained two-slot gutter model instead of the old stacked active ancestry presentation.
- `LspStructuralAnchorDTO` and `prometeu-lsp` now expose a dedicated structural-anchor transport surface separate from `documentSymbols`.
- `SemanticIndex` derives exact structural anchors for Studio consumption.
- Studio and semantic-read specs now define the two-indicator gutter model, the dedicated structural-anchor surface, and the frontend-owned exact-anchor contract.
- Tests now cover smallest-containing-range selection, immediate-parent selection, structural-anchor transport, and anchor-aware rendering.
## Patterns and Algorithms
### Pattern: Split Local Active State from Exact Structural Geometry
The useful decomposition is:
- derive active editor context locally from the current structural range set;
- derive exact guide geometry from frontend-owned structural anchors.
The editor can therefore ship a useful first wave without inventing the long-term anchor contract.
### Pattern: Use the Smallest Containing Range as the Active Scope
When multiple structural ranges contain the caret, the active scope must be the nearest one, not the largest semantic owner.
That keeps the editor aligned with the user's current editing neighborhood.
### Example: Anchor Upgrade Path
The resulting flow is:
1. semantic read returns structural ranges and, when available, exact structural anchors;
2. Studio computes `activeScope` and `activeContainer` from containment;
3. gutter rendering uses exact anchor positions when present;
4. no fallback contract is allowed to redefine exact anchoring through source scanning.
## Pitfalls
- Do not overload `documentSymbols` with guide-only anchor data.
- Do not restore the full stacked ancestry gutter as the default active-scope experience.
- Do not treat brace scanning as a production contract for exact anchors.
- Do not promote high-level owners such as function or type when a nearer structural ancestor exists.
- Do not hardcode theme or stroke policy into the semantic guide model.
## References
- `DEC-0014` Code Editor active container, active scope, and frontend-owned structural anchors
- `PLN-0030` Wave 1 editor implementation for active container and active scope gutter indicators
- `PLN-0031` Structural anchor semantic surface specification for Studio semantic read
- `PLN-0032` Frontend structural-anchor payload propagation and anchor-aware test coverage
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
- `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/dtos/LspStructuralAnchorDTO.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/models/SemanticIndex.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideModel.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideGraphicFactory.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
## Takeaways
- Active structure and exact anchor geometry should be modeled as separate concerns.
- The default gutter becomes much clearer when it shows only the nearest scope context.
- Exact structural anchors belong to a frontend-owned semantic surface, not to Studio heuristics.

124
discussion/lessons/DSC-0017-studio-editor-inline-type-hints-for-let-bindings/LSN-0035-frontend-owned-inline-hints-with-decorative-inline-rendering.md Normal file
View File

@ -0,0 +1,124 @@
---
id: LSN-0035
ticket: studio-editor-inline-type-hints-for-let-bindings
title: Frontend-Owned Inline Hints with Decorative Inline Rendering
created: 2026-04-06
tags: [studio, editor, inline-hints, lsp, compiler, pbs, type-inference, rendering]
---
## Context
The repository needed inline type hints for inferred PBS `let` bindings, but the real architectural issue was broader than one PBS feature.
Without a disciplined split, inline hints could easily drift into one of two broken designs:
- Studio invents semantic hint policy on its own,
- or LSP becomes a hidden semantic owner instead of a transport layer.
The work closed that gap by treating inline hints as a host-generic capability with frontend-owned meaning and Studio-owned decorative rendering.
## Key Decisions
### Keep Hint Existence and Meaning Frontend-Owned
**What:**
Frontends decide whether a hint exists, where it anchors, and which semantic payload it carries.
The initial PBS wave emits inferred-type hints only for eligible `let` bindings whose types are omitted in source.
**Why:**
Hint policy is semantic product behavior.
The host should render hints, not decide which language constructs deserve them.
**Trade-offs:**
Each frontend must publish and test its own hint policy explicitly.
That extra responsibility is better than growing a fake host-wide semantic rule set.
### Make LSP the Dedicated Hint Transport Bridge
**What:**
`prometeu-lsp` now exposes a dedicated inline-hint DTO surface and transports frontend-produced hints through analyze results without inventing content.
**Why:**
Hints need a stable contract boundary between frontend production and Studio rendering.
Transport ownership is necessary, but semantic authorship must remain outside the transport layer.
**Trade-offs:**
The semantic-read contract becomes richer and needs explicit tests for anchor stability and degraded-analysis preservation.
That is acceptable because it prevents hint content from leaking into host heuristics.
### Render Hints Inline but Keep Them Decorative
**What:**
Studio now renders transported hints inline in the editor flow while preserving text-only editing semantics.
Hints do not become persisted text, copy/paste content, or caret-selection content.
**Why:**
The decision required real inline rendering as the final UX rather than a permanent approximation.
At the same time, the document model had to remain stable and text-owned.
**Trade-offs:**
The editor rendering path is more complex because it must project hint text into the visible surface while protecting the canonical source buffer.
That complexity is justified because it preserves both the UX target and the text-model boundary.
## Final Implementation
The final state landed across specs, frontend production, LSP transport, and Studio rendering:
- Studio specs and semantic-read specs now define inline hints as frontend-owned, decorative-only, host-generic, and preserved under partial degradation.
- The compiler pipeline spec now states that inline hint semantics remain frontend-authored and must not move into Studio or LSP.
- PBS flow analysis now emits `PbsInlineHintSurface` values for eligible inferred `let` bindings and suppresses hints for explicitly typed bindings.
- `LspInlineHintDTO`, `SemanticSession`, `LspSemanticReadPhase`, and `LspSemanticAnalyseService` now transport inline hints as a dedicated semantic-read surface.
- `EditorDocumentInlineHintRouter`, `EditorInlineHintProjection`, and `EditorWorkspace` now render transported hints inline while stripping them back out of mutation and persistence flows.
- Tests cover DTO invariants, transport shape, partial-degradation preservation, PBS eligibility, and decorative editor behavior.
## Patterns and Algorithms
### Pattern: Separate Semantic Ownership from Rendering Ownership
The correct flow is:
1. frontend decides hint policy and payload;
2. LSP transports that payload without reinterpretation;
3. Studio renders it mechanically.
That preserves one semantic authority while still giving the host a reusable capability.
### Pattern: Project Inline Decorations Without Mutating the Source Buffer
Inline hints can be shown inside the editor flow by maintaining a display projection that includes decorations while keeping a canonical text-only source representation for editing and saving.
This gives real inline UX without making hints part of the file model.
### Pattern: Preserve Valid Local Signal Under Degradation
When some hint spans fail, the system should omit only those spans and keep valid ones.
Partial degradation is easier to reason about when hint payloads are independent entries rather than a monolithic all-or-nothing render switch.
## Pitfalls
- Do not let Studio synthesize hint content for constructs the frontend did not publish.
- Do not let LSP infer host-owned hint policy when the frontend emits no hints.
- Do not let inline hints leak into persisted text, copy/paste, or caret movement semantics.
- Do not keep an approximate overlay as the silent long-term architecture after the decision locked real inline rendering.
- Do not emit inferred-type hints for bindings that already carry explicit type syntax.
## References
- `DEC-0015` Studio Editor Inline Type Hints Contract and Rendering Model
- `PLN-0033` Inline hint specification and contract propagation
- `PLN-0034` LSP inline hint transport contract
- `PLN-0035` PBS inline type hint payload production
- `PLN-0036` Studio inline hint rendering and rollout
- `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md`
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PbsInlineHintSurface.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowBodyAnalyzer.java`
- `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/dtos/LspInlineHintDTO.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspSemanticReadPhase.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorInlineHintProjection.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
## Takeaways
- Inline hints stay maintainable when semantic ownership remains in the frontend.
- Dedicated transport is necessary, but transport must not become semantic authorship.
- Real inline rendering is compatible with a text-only canonical buffer when the editor uses an explicit projection boundary.

121
discussion/lessons/DSC-0021-studio-frontend-editor-write-and-save-wave/LSN-0036-vfs-owned-frontend-edit-and-save-wave.md Normal file
View File

@ -0,0 +1,121 @@
---
id: LSN-0036
ticket: studio-frontend-editor-write-and-save-wave
title: VFS-Owned Frontend Edit and Save Wave
created: 2026-04-06
tags: [studio, editor, frontend, write, save, vfs, lsp, access-policy, persistence]
---
## Context
The first editor write wave had deliberately kept frontend files hard `read-only` while semantic-read support shipped through `prometeu-lsp`.
That left a controlled but incomplete product state:
- frontend documents already delivered semantic value,
- but editing and saving were still blocked,
- and the repository needed to decide whether that next wave would preserve or collapse the established ownership boundaries.
This discussion closed that transition by releasing frontend editing and save together under the existing VFS ownership model.
## Key Decisions
### Release Frontend Edit and Save in the Same Wave
**What:**
Frontend editing and frontend save now ship together rather than as separate product steps.
**Why:**
Editable-but-unsaveable frontend buffers would create a half-owned state and weaken the document boundary the repository had already stabilized.
**Trade-offs:**
The first write release has to be coherent across access mode, dirty tracking, save, UI enablement, and specs.
That is more coordinated work, but it avoids a broken intermediate product shape.
### Keep `prometeu-vfs` as the Sole Document and Persistence Owner
**What:**
`prometeu-vfs` remains the sole owner of frontend writable snapshots, access mode, dirty tracking, save, and save-all behavior.
Studio UI consumes those rights, and `prometeu-lsp` continues to consume VFS-backed snapshots for semantics.
**Why:**
The repository had already separated document ownership, semantic ownership, and UI consumption.
Releasing frontend editing should not reopen that boundary.
**Trade-offs:**
VFS carries more explicit frontend editing responsibility, and Studio must stay disciplined about consuming rather than deriving policy.
That is preferable to splitting persistence logic across UI and semantic tooling layers.
### Apply the First Write Wave to All Supported Frontend Files
**What:**
The first frontend write wave applies to all currently supported frontend-scoped files recognized by the VFS/frontend boundary.
**Why:**
The accepted decision explicitly rejected a temporary subset or per-file narrowing rule for this wave.
Once frontend editing is released, the supported frontend scope should behave coherently.
**Trade-offs:**
The wave requires confidence in the existing supported-file boundary.
That is a better constraint than introducing new ad hoc file-class heuristics during rollout.
## Final Implementation
The completed implementation propagated the decision across specs, VFS, and Studio:
- Studio specs now state that supported frontend-scoped documents may be editable when `prometeu-vfs` classifies them as editable and that semantic-read remains a consumer-only boundary.
- `FilesystemVfsProjectDocument` now classifies supported frontend documents as `EDITABLE`, accepts `updateDocument`, and persists them through `saveDocument` and `saveAllDocuments`.
- VFS tests now cover frontend editable access mode, in-memory mutation, save persistence, and save-all behavior.
- Studio editor session behavior now treats frontend editable files as ordinary VFS-authorized editable tabs rather than as hard `read-only` exceptions.
- Save and save-all continue to route through the existing VFS-owned path with no new persistence ownership in Studio UI or `prometeu-lsp`.
## Patterns and Algorithms
### Pattern: Release Mutation Together with Persistence
If a document class becomes editable, the same owner must also own save in the same release wave.
Otherwise the product creates a draft-only state that undermines the document boundary.
### Pattern: Keep UI as a Policy Consumer
The stable flow remains:
1. VFS classifies the document and exposes access context;
2. Studio enables editing and save based on that context;
3. LSP reads the same VFS-backed snapshots for semantics.
No layer needs to guess or duplicate ownership rules.
### Example: Frontend Save Path
The resulting save flow is:
1. a supported frontend file opens through VFS as `EDITABLE`;
2. Studio mutates the VFS-owned in-memory snapshot;
3. save and save-all persist through VFS;
4. LSP continues reading the VFS-backed snapshot without becoming a persistence owner.
## Pitfalls
- Do not release frontend editing without frontend save in the same wave.
- Do not move dirty tracking or persistence into Studio UI just because the editor hosts the interaction.
- Do not move access-policy or persistence ownership into `prometeu-lsp`.
- Do not introduce a narrowed temporary subset of supported frontend files without a new explicit decision.
- Do not let specs or UX surfaces keep describing frontend files as hard `read-only` after the wave has shipped.
## References
- `DEC-0019` Enable Frontend Editing and Save in the Studio Code Editor
- `PLN-0040` Implement the frontend editor write and save wave through VFS ownership
- `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-vfs/prometeu-vfs-v1/src/test/java/p/studio/vfs/FilesystemVfsProjectDocumentTest.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorOpenFileSession.java`
## Takeaways
- Frontend editing is coherent only when save ownership lands in the same wave.
- VFS remains the right owner for access policy, dirty state, and persistence even for frontend documents.
- The architecture stays stable when Studio consumes policy and LSP consumes snapshots instead of either layer becoming a second document owner.

123
discussion/workflow/agendas/AGD-0017-studio-editor-scope-guides-and-brace-anchoring.md
View File

@ -1,123 +0,0 @@
---
id: AGD-0017
ticket: studio-editor-scope-guides-and-brace-anchoring
title: Scope guides do Code Editor com active container, active scope e ancoragem estrutural
status: accepted
created: 2026-04-03
resolved: 2026-04-03
decision:
tags:
- studio
- editor
- scope-guides
- braces
- semantic-read
- frontend-contract
---
## Pain
Os scope guides do Code Editor hoje comunicam hierarquia de escopo, mas ainda falham em dois pontos visuais importantes:
- o guide nao comeca no `{` real do bloco; ele nasce aproximadamente no meio da linha inicial do simbolo;
- o editor nao destaca o escopo em que o cursor esta, entao o usuario nao recebe feedback imediato de qual bloco esta ativo.
Isso deixa a feature util, mas incompleta. Em blocos aninhados, a leitura espacial do editor perde precisao justamente no momento em que o guide deveria ajudar mais.
## Context
Domain owner: `studio`
Owner surfaces: `docs/specs/studio/5. Code Editor Workspace Specification.md`, `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
Cross-domain input: frontends que produzem `documentSymbols()` para o Studio
Superficies relevantes hoje:
- `EditorWorkspace` monta os guides a partir de `analysis.documentSymbols()` e repassa o modelo para a paragraph graphic factory em `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`;
- `EditorDocumentScopeGuideModel` projeta guias por linha com `depth` e `GuideSegmentKind`, mas nao carrega coluna nem offset estrutural do brace em `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideModel.java`;
- `EditorDocumentScopeGuideGraphicFactory` desenha `START` e `END` a partir do centro vertical da linha, nao de um token estrutural real, em `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideGraphicFactory.java`;
- os testes atuais do modelo validam apenas shape por linha, nao ancoragem precisa de brace nem estado ativo por cursor, em `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorDocumentScopeGuideModelTest.java`.
Hoje o schema semantico exposto ao Studio entrega `documentSymbols` com `LspRangeDTO(startOffset, endOffset)`, o que e suficiente para inferir linhas de escopo, mas nao suficiente para afirmar onde o `{` de abertura e o `}` de fechamento realmente estao quando:
- o brace esta em outra coluna da mesma linha;
- o header do simbolo se estende por mais de uma linha;
- a linguagem tem formas de bloco em que o range do simbolo nao coincide com o token estrutural que queremos destacar.
## Open Questions
- [x] O escopo ativo deve ser definido sempre como o menor range estrutural que contem o caret, ou existem casos em que o Studio deve promover o parent em vez do bloco mais interno?
Fechado: `active scope` deve ser sempre o menor range estrutural que contem o caret.
- [x] Como o Studio escolhe o `active container` quando o caret esta em blocos aninhados: funcao owner, tipo owner, ou simplesmente o menor ancestor acima do `active scope`?
Fechado: `active container` deve ser o ancestor estrutural imediato acima do `active scope`, sem excecoes semanticas especiais para funcao, tipo ou outro owner.
- [x] O guide deve ancorar no token estrutural real (`{`/`}`), ou basta uma heuristica local no editor que encontre o primeiro brace plausivel dentro do range do simbolo?
Fechado: a ancoragem exata nao deve depender de heuristica textual local como contrato final; o objetivo correto e um anchor estrutural real.
- [x] O contrato correto para essa precisao estrutural pertence ao frontend/LSP semantic read, ou o Studio deve derivar isso localmente a partir do texto do documento?
Fechado: a precisao estrutural pertence ao frontend e deve ser exposta ao Studio como metadata semanticamente owned pelo produtor da linguagem.
- [x] Como tratar linguagens que nao usam braces ou usam formas mistas de delimitacao, sem acoplar o Studio a PBS?
Fechado: o contrato deve falar em `structural anchors` genericos, nao em braces como primitivo normativo.
- [x] O schema atual de `documentSymbols` deve ser enriquecido, ou devemos introduzir uma surface estrutural paralela dedicada a guides/brackets?
Fechado: devemos introduzir uma surface semantica propria para guides/anchors em vez de inflar `documentSymbols`.
## Options
### Option A - Heuristica local no Studio sobre os ranges atuais
- **Approach:** Manter o contrato atual de `documentSymbols` e fazer o Studio procurar braces plausiveis dentro do texto/range de cada simbolo, alem de calcular o escopo ativo localmente pelo caret.
- **Pro:** Menor custo inicial e pouca mudanca de contrato entre frontend e Studio.
- **Con:** A heuristica tende a ser fragil para headers multiline, linguagens sem braces, ranges amplos demais e futuras linguagens com sintaxe diferente de PBS.
- **Maintainability:** Media para baixa. Resolve rapido, mas cristaliza logica estrutural no host visual em vez de no owner da linguagem.
### Option B - Metadata estrutural explicita fornecida pelo frontend
- **Approach:** Enriquecer o payload semantico consumido pelo Studio com posicoes estruturais explicitas para abertura/fechamento de blocos, ou com uma surface propria para scope/bracket guides; o editor usa esse contrato para ancoragem exata e para determinar o escopo ativo.
- **Pro:** Fecha ownership correto no frontend, preserva neutralidade do Studio em relacao a sintaxe e permite ancoragem precisa sem heuristica textual fraca.
- **Con:** Exige mudar o contrato entre semantic read e Studio, propagar implementacao para o frontend e decidir um schema que nao fique PBS-especifico.
- **Maintainability:** Forte. A precisao estrutural fica no produtor semantico, onde o parse e o conhecimento de linguagem ja existem.
### Option C - Abordagem hibrida em duas waves
- **Approach:** Implementar primeiro um gutter minimalista com no maximo duas linhas visiveis: `active container` e `active scope`, ambos calculados localmente a partir dos ranges atuais; tratar a ancoragem exata no `{` como uma extensao posterior baseada em metadata estrutural explicita.
- **Pro:** Entrega contexto e foco ao mesmo tempo, com pouco ruido, sem bloquear na extensao de contrato e sem puxar o Studio para heuristica sintatica como solucao final.
- **Con:** Exige definir semanticamente o que conta como `active container` e pode exigir retrabalho pequeno no modelo do editor quando a metadata estrutural chegar.
- **Maintainability:** Boa, se a primeira wave permanecer estritamente limitada a duas linhas sem ancestry aberta.
## Discussion
Os dois sintomas nao tem o mesmo peso arquitetural.
Destacar o escopo ativo parece um problema majoritariamente local do editor, especialmente se a primeira wave for minimalista e restrita ao gutter:
- o `CodeArea` ja conhece caret/paragrafo atual;
- o modelo atual ja conhece os ranges de escopo por linha;
- em primeira aproximacao, o editor consegue descobrir qual range contem o cursor sem precisar saber a coluna exata do `{`;
- renderizar no maximo duas linhas (`active container` e `active scope`) preserva contexto sem voltar ao mapa completo de ancestry.
Ja a ancoragem precisa do guide no brace parece um problema de contrato estrutural:
- o modelo atual nao sabe onde o brace real esta;
- usar apenas `startOffset/endOffset` do simbolo empurra heuristica sintatica para dentro do Studio;
- isso fica especialmente fraco num editor que ja foi desenhado para ser multi-frontend.
Por isso, vale separar claramente:
1. `active container` e `active scope` como comportamento visual local, minimalista, restrito ao gutter e derivado dos ranges atuais;
2. `brace anchoring` como capacidade estrutural que talvez exija metadata adicional do frontend.
O risco de tentar resolver tudo localmente no Studio e transformar o host visual em pseudo-parser por linguagem.
O risco oposto e bloquear uma melhoria visual simples do cursor enquanto esperamos um contrato estrutural maior ficar pronto.
## Resolution
Recommended direction: seguir com **Option C**.
A agenda deve convergir para uma decisao com os seguintes fechamentos:
1. a primeira wave deve manter o scope indicator no gutter, de forma minimalista e sem poluicao visual;
2. a primeira wave pode renderizar no maximo duas linhas no gutter: `active container` e `active scope`, sem ancestry arbitraria e sem mapa completo de guides;
3. `active scope` deve ser o menor range estrutural que contem o caret;
4. `active container` deve ser o ancestor estrutural imediato acima do `active scope`;
5. o destaque desses estados pelo cursor deve ser tratado como capacidade local do editor, usando os ranges semanticos ja disponiveis, desde que a regra fique language-agnostic;
6. a apresentacao visual concreta desses indicadores deve continuar frontend-owned; o contrato do Studio nao deve fixar cores, tracos ou estilos especificos como regra normativa;
7. a ancoragem exata do guide nao deve ser resolvida por heuristica textual como contrato final;
8. a precisao estrutural deve ser exposta por metadata frontend-owned;
9. essa metadata deve falar em `structural anchors` genericos, nao em braces como primitivo normativo;
10. guides/anchors devem viver em uma surface semantica propria, em vez de estender `documentSymbols`.
Next step suggestion: converter esta agenda em uma `decision` que feche o boundary entre Studio e frontend para structural scope metadata, diferencie formalmente `active scope` de `brace anchor`, e declare a wave inicial aceitavel para o Code Editor.

112
discussion/workflow/agendas/AGD-0018-studio-editor-inline-type-hints-for-let-bindings.md
View File

@ -1,112 +0,0 @@
---
id: AGD-0018
ticket: studio-editor-inline-type-hints-for-let-bindings
title: Inline Type Hints for Let Bindings in the Studio Editor
status: accepted
created: 2026-04-03
resolved: 2026-04-03
decision: DEC-0015
tags: [studio, editor, inline-hints, inlay-hints, lsp, pbs, type-inference]
---
## Pain
O Code Editor do Studio já mostra semantic highlighting e structure guides, mas ainda não ajuda o usuário a visualizar tipos inferidos localmente em bindings como `let value = expr;`.
Isso cria duas fricções:
- o usuário perde feedback rápido sobre o tipo efetivo inferido pelo frontend;
- o editor fica atrás de IDEs que mostram hints não textuais inline para reduzir ambiguidade sem poluir o source.
## Context
- O editor atual usa `CodeArea` do RichTextFX com `StyleSpans`, gutter graphics e semantic read vindo do LSP.
- O frontend PBS já infere o tipo de `let` durante a análise de fluxo, mas esse dado não é publicado como uma surface explícita consumível pelo editor.
- O Studio hoje não possui uma camada de rendering inline equivalente a inlay hints do IntelliJ.
- O repositório já adotou a direção de presentation frontend-owned para semantic rendering, mas inlay hints de tipo parecem tocar uma fronteira diferente: parte do dado nasce no frontend/LSP, parte do rendering nasce no host editor.
## Open Questions
- [x] Qual deve ser o owner do payload do hint: frontend puro, LSP derivado, ou Studio como consumer de uma surface semântica padronizada?
Resposta: o frontend define a surface e o payload; o LSP fixa e transporta o contrato; o Studio renderiza.
- [x] O hint deve ser limitado a `let` com tipo omitido ou também cobrir `const`, parâmetros inferidos futuros e outros binders?
Resposta: quem decide quais hints existem é o frontend; se o hint vier no contrato, o Studio imprime.
- [x] O rendering deve ser inline real no fluxo do texto ou uma aproximação visual menos invasiva numa primeira wave?
Resposta: o estado final obrigatório da feature é inline real; aproximação visual só é aceitável como etapa transitória.
- [x] O hint precisa participar de hit testing, seleção, caret navigation e copy/paste, ou deve ser estritamente decorativo?
Resposta: o hint é totalmente decorativo.
- [x] Em caso de erro parcial de análise, o editor deve manter hints estáveis dos spans válidos ou desligar hints do documento?
Resposta: manter hints estáveis dos spans válidos.
## Options
### Option A - LSP Inlay Hints + Inline Rendering Real no Editor
- **Approach:** adicionar uma surface explícita de inlay hints no LSP para bindings `let` e evoluir o Studio para renderização inline não textual no fluxo do editor.
- **Pro:** modelo mais correto, escalável e alinhado com a UX esperada de IDE.
- **Con:** exige mudança estrutural maior no editor, possivelmente acima do que `CodeArea + StyleSpans` entrega nativamente.
- **Maintainability:** boa no longo prazo se virar um primitive reutilizável para hints, parameter names e outras decorações inline.
### Option B - LSP Inlay Hints + Overlay Visual Aproximado na Primeira Wave
- **Approach:** publicar hints no LSP, mas renderizar numa camada visual acoplada ao editor sem inserir segmentos inline reais no documento na primeira etapa.
- **Pro:** destrava valor ao usuário mais cedo e reduz risco inicial na infraestrutura do editor.
- **Con:** pode divergir do comportamento esperado de caret, wrapping e alinhamento fino; corre risco de parecer remendo se ficar permanente.
- **Maintainability:** aceitável apenas se explicitamente tratada como wave transitória rumo a rendering inline real.
### Option C - Não criar inlay hints; usar apenas hover/inspector
- **Approach:** expor tipo inferido via hover, status bar ou helper panel em vez de hint persistente na linha.
- **Pro:** implementação menor e compatível com a arquitetura atual.
- **Con:** não resolve o objetivo principal de feedback contínuo e local; perde ergonomia frente ao benchmark citado.
- **Maintainability:** simples, mas funcionalmente insuficiente para a dor descrita.
## Discussion
O ponto crítico não é só “mostrar texto cinza depois do nome”. A decisão precisa fechar três contratos:
1. contrato de dados:
o frontend/LSP precisa publicar um hint estável com anchor, conteúdo textual e política de exibição;
2. contrato de rendering:
o Studio precisa decidir se quer suportar uma primitive geral de adornos inline ou apenas uma solução pontual para `let`;
3. contrato de interação:
hints não podem contaminar o conteúdo real do documento, mas também não podem quebrar leitura, seleção, scroll ou layout.
O risco de uma solução ad hoc é repetir o problema já visto em outras áreas: valor imediato, mas sem primitive reusável e com alto custo para generalizar depois.
Ao mesmo tempo, exigir inline rendering “perfeito” logo de saída pode atrasar demais uma ergonomia que já tem valor alto para PBS.
Direção já aceita nesta agenda:
1. ownership e contrato:
o frontend oferece a surface de hints, o LSP a transforma em contrato estável de transporte/consumo, e o Studio apenas renderiza;
2. policy de conteúdo:
o Studio não escolhe quais hints existem; se o frontend publicar hint válido no contrato, o host imprime;
3. rendering target:
a feature só fecha corretamente quando o hint for inline real; qualquer overlay aproximado deve ser explicitamente tratado como etapa transitória;
4. interaction model:
hints são decorativos e não alteram texto, seleção, copy/paste ou modelo documental;
5. degradação parcial:
hints válidos devem sobreviver mesmo quando o restante da análise do documento estiver parcialmente degradado.
## Resolution
Recomendação inicial:
- seguir com uma discussion owner de `studio/editor`;
- tratar o problema como uma capability formal de `inlay hints` do editor, não como uma exceção do PBS;
- modelar o contrato como frontend-defined, LSP-enforced/transported, Studio-rendered;
- manter o Studio host-agnostic quanto ao conteúdo do hint;
- aceitar waves transitórias apenas se convergirem explicitamente para inline real;
- preservar hints válidos sob degradação parcial de análise.
Próximo passo sugerido:
- derivar um `plan` que separe explicitamente:
contrato FE/LSP,
primitive de rendering no Studio,
wave transitória opcional,
testes de degradação parcial e comportamento decorativo.

120
discussion/workflow/agendas/AGD-0022-studio-frontend-editor-write-and-save-wave.md
View File

@ -1,120 +0,0 @@
---
id: AGD-0022
discussion: DSC-0021
ticket: studio-frontend-editor-write-and-save-wave
title: Enable Frontend Editing and Save in the Studio Code Editor
status: accepted
created: 2026-04-04
updated: 2026-04-04
owner: studio
tags: [studio, editor, frontend, write, save, vfs, lsp, pbs, access-policy]
---
## Problem
The Studio Code Editor already delivers frontend semantic-read value through `prometeu-lsp`, but frontend documents are still hard `read-only`.
That leaves the FE editing wave unfinished:
- frontend files can be opened, analyzed, highlighted, and navigated;
- but they cannot be edited or saved;
- and the current contract explicitly says that FE editing requires a separate decision.
The next step is to define how FE mutation and save rights should be released without breaking the VFS/LSP/editor ownership split that the repository has already stabilized.
## Context
Domain owner: `studio`.
The current durable constraints are already clear:
1. `prometeu-vfs` owns document classification, access mode, snapshots, and save behavior;
2. `prometeu-lsp` is a semantic consumer of VFS-backed snapshots and must not absorb save or access-policy ownership;
3. Studio UI is a consumer of both boundaries and must not re-derive document rights locally;
4. frontend semantic-read was intentionally released before frontend edit rights;
5. FE edit rights now require a new explicit discussion and decision.
This means the new wave cannot be framed as “let the editor mutate text and figure out persistence later”.
If FE editing is released, it must be released through the same document-runtime owner that already controls access and save semantics.
## Open Questions
1. Should FE editing be released only together with FE save in the same wave?
2. Must FE editable snapshots remain owned by `prometeu-vfs`, exactly like non-frontend editable documents?
3. How should `prometeu-lsp` consume dirty FE snapshots after mutation: on-demand analyze only, background refresh, or both?
4. Are FE edit rights universal for all frontend-scoped supported files, or do they need an additional narrowing rule in this first FE write wave?
5. What explicit safeguards are needed so FE editing does not accidentally turn `prometeu-lsp` into the document owner?
## Options
### Option 1: Allow FE editing in the editor before FE save exists
The editor would accept FE text mutation locally, and LSP could consume that dirty text, but FE save would remain unavailable or deferred.
Tradeoffs:
- appears to unlock FE editing quickly;
- creates a half-owned document state with unclear persistence semantics;
- weakens the current VFS ownership model;
- encourages exactly the “editor mutates first, persistence later” drift the repository has avoided so far.
This option is weak and should be rejected.
### Option 2: Release FE editing and FE save together through `prometeu-vfs`
FE documents become editable only when `prometeu-vfs` can own their writable snapshots, dirty tracking, and save behavior.
The editor consumes that access mode, and `prometeu-lsp` continues to analyze VFS-backed FE snapshots as a consumer.
Tradeoffs:
- preserves the current architecture cleanly;
- avoids split-brain ownership between editor, VFS, and LSP;
- makes FE write behavior coherent on day one;
- requires a broader implementation wave than a UI-only unlock.
This is the strongest option.
### Option 3: Let `prometeu-lsp` become the temporary owner of editable FE session text
LSP would hold the live FE text state because it already consumes FE semantics, and save integration would come later.
Tradeoffs:
- seems convenient because FE semantics already live there;
- collapses semantic ownership into document ownership;
- directly conflicts with the established VFS boundary;
- would make the previous editor/VFS/LSP split editorially and architecturally inconsistent.
This option should be rejected.
## Recommendation
Adopt Option 2.
Recommended direction:
1. FE editing and FE save should be released in the same wave.
2. `prometeu-vfs` should remain the sole owner of FE writable snapshots, access mode, dirty tracking, and persistence.
3. `prometeu-lsp` should continue as a semantic consumer of VFS-backed FE snapshots, including dirty in-memory FE state.
4. Studio UI should remain a policy consumer and must not introduce FE-local save or access heuristics outside the VFS contract.
5. The first FE write wave should explicitly define scope, save semantics, user-visible access changes, and any resulting LSP refresh model.
## Next Step
If this agenda is accepted, convert it into a decision that normatively locks:
- whether FE edit and FE save release together;
- VFS ownership of FE writable snapshots and save behavior;
- LSP consumption rules for dirty FE snapshots;
- and the exact scope of the first FE write wave.
## Resolution
Accepted on 2026-04-04.
The discussion is closed with the following resolution:
1. FE editing and FE save release together in the same wave.
2. `prometeu-vfs` remains the sole owner of FE writable snapshots, access mode, dirty tracking, and persistence.
3. `prometeu-lsp` continues as a semantic consumer of VFS-backed FE snapshots, including dirty in-memory FE state, but no new LSP implementation work is part of the immediate execution wave.
4. The first FE write wave applies to all frontend-scoped supported files rather than introducing an additional narrowing rule.

147
discussion/workflow/decisions/DEC-0014-studio-editor-active-scope-and-structural-anchors.md
View File

@ -1,147 +0,0 @@
---
id: DEC-0014
ticket: studio-editor-scope-guides-and-brace-anchoring
title: Code Editor active container, active scope, and frontend-owned structural anchors
status: accepted
created: 2026-04-03
accepted: 2026-04-03
agenda: AGD-0017
plans:
- PLN-0030
- PLN-0031
- PLN-0032
tags:
- studio
- editor
- scope-guides
- semantic-read
- frontend-contract
- structural-anchors
---
## Decision
The Studio Code Editor SHALL keep scope indicators in the gutter.
The initial wave SHALL render at most two simultaneous structural indicators:
1. `active container`
2. `active scope`
The Studio MUST NOT render the full ancestry map or the current multi-guide stack as the default active-scope presentation.
`active scope` SHALL be defined as the smallest structural range that contains the caret.
`active container` SHALL be defined as the immediate structural ancestor of `active scope`.
The Studio SHALL determine `active container` and `active scope` locally from semantic ranges already available to the editor, provided that the rule remains language-agnostic.
The concrete visual presentation of these two indicators SHALL remain frontend-owned. The Studio contract MUST NOT normatively fix colors, stroke style, dashed versus solid rendering, or equivalent stylistic choices.
Exact guide anchoring MUST NOT rely on local textual heuristics as the final contract. Exact anchoring SHALL be backed by frontend-owned structural metadata.
That structural metadata SHALL be expressed as generic `structural anchors`, not as PBS-specific brace semantics. The contract MUST remain language-agnostic and applicable to languages that do not use `{` / `}` as primary delimiters.
Structural anchors and guide-specific structural data SHALL live in a dedicated semantic surface. They MUST NOT be folded into `documentSymbols` as an overloaded extension of the outline/navigation payload.
## Rationale
The current gutter guides already prove that structural ranges are useful, but the existing presentation is too noisy and not precise enough:
- multiple simultaneous guide columns create visual pollution;
- the current guide start/end positions are derived from symbol line ranges, not from exact structural anchors;
- the current model is good enough to identify containing ranges, but not good enough to express precise opening/closing structure.
The accepted direction separates two concerns that have different architectural weights:
- `active container` and `active scope` are local editor-state projections and can be derived from existing semantic ranges;
- exact structural anchoring is a language-owned concern and belongs in frontend metadata rather than Studio-local syntax heuristics.
Restricting the default visualization to at most two indicators preserves context without reviving the clutter of a full ancestry map.
Keeping visual styling frontend-owned preserves the existing design direction in which semantic presentation belongs to the frontend rather than to Studio-global hardcoded rendering rules.
## Technical Specification
### 1. Gutter Indicator Model
The editor gutter SHALL support exactly two semantic slots for active structural indication:
- `activeContainer`
- `activeScope`
The first implementation wave MAY omit `activeContainer` when no valid ancestor exists. It MUST NOT synthesize a non-existent container.
The editor MUST compute `activeScope` by selecting the smallest structural range that contains the caret offset.
The editor MUST compute `activeContainer` by selecting the immediate parent structural range of `activeScope`.
The editor MUST NOT promote a higher semantic owner such as function, type, or module when a nearer structural ancestor exists.
### 2. Presentation Ownership
The editor SHALL expose enough state for the presentation layer to distinguish:
- container indicator
- scope indicator
The decision intentionally leaves the following presentation properties non-normative:
- color
- opacity
- stroke thickness
- dashed versus solid treatment
- cap styling
- equivalent visual emphasis rules
Those choices SHALL remain frontend-owned or presentation-owned.
### 3. Structural Anchoring
Exact anchor positions for guide start/end SHALL come from semantic structural metadata produced by the language/frontend side.
Studio MUST treat those anchors as generic structural positions rather than brace-specific tokens.
The metadata model MUST support languages where structural delimiters are:
- braces
- keywords
- indentation-derived constructs
- mixed delimiter schemes
### 4. Semantic Surface Boundary
`documentSymbols` SHALL remain the outline/navigation surface.
Structural guide metadata SHALL be introduced as a distinct semantic surface dedicated to:
- structural ranges
- structural parent/child relationships when needed
- structural anchors used by guide rendering
Studio MUST NOT infer the final structural contract by scanning source text for likely braces inside symbol ranges.
Local heuristics MAY exist only as temporary debugging aids during development. They MUST NOT become the canonical production contract.
### 5. Propagation Targets
This decision SHALL propagate to:
- Studio editor implementation in `prometeu-studio`
- Studio-facing semantic read contracts in `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
- Code Editor presentation and interaction behavior in `docs/specs/studio/5. Code Editor Workspace Specification.md`
- frontend-produced semantic payloads that eventually expose structural anchors
- tests covering active scope selection, active container selection, and anchor-aware rendering
## Constraints
- The decision does not authorize inline indentation-column guides inside the main code text area as the primary first-wave solution.
- The decision does not authorize restoring the existing full stacked guide rendering as the default active-scope UX.
- The decision does not fix a specific visual palette or theme mapping.
- The decision does not yet define the exact serialized schema of the future structural-anchor surface; that belongs in plan/spec work derived from this decision.
- The decision does not require immediate availability of structural anchors to ship the first-wave `active container` and `active scope` gutter behavior.
## Revision Log
- 2026-04-03: Initial draft from AGD-0017.
- 2026-04-03: Accepted and split into execution plans PLN-0030, PLN-0031, and PLN-0032.

160
discussion/workflow/decisions/DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md
View File

@ -1,160 +0,0 @@
---
id: DEC-0015
ticket: studio-editor-inline-type-hints-for-let-bindings
title: Studio Editor Inline Type Hints Contract and Rendering Model
status: accepted
created: 2026-04-03
accepted: 2026-04-03
agenda: AGD-0018
plans: [PLN-0033, PLN-0034, PLN-0035, PLN-0036]
tags: [studio, editor, inline-hints, inlay-hints, lsp, frontend-contract, type-inference]
---
## Decision
O Studio SHALL support inline type hints as a first-class editor capability rather than as a PBS-only exception.
The ownership model for the capability is normatively locked as follows:
- the frontend MUST define which hints exist, where they anchor, and what semantic payload they carry;
- the LSP MUST define and enforce the transport contract for those hints and MUST transport frontend-produced hint data to the Studio consumer;
- the Studio MUST render transported hints and MUST NOT invent frontend hint content on its own.
The final user-visible form of the feature MUST be real inline rendering inside the editor flow.
Any approximate visual solution MAY be used only as a transitional implementation stage and MUST be explicitly treated as an intermediate rollout step rather than as the final contract.
Inline hints produced under this capability MUST be decorative only.
Inline hints MUST NOT:
- mutate document text;
- participate as document content in copy/paste;
- redefine selection semantics;
- redefine caret movement semantics;
- become part of the persisted file model.
When analysis is partially degraded, the Studio MUST preserve and render hint spans that remain valid under the transported contract rather than disabling all hints for the whole document.
The host policy for what receives hints is frontend-owned.
If a frontend publishes valid hints under the LSP contract, the Studio MUST render them.
If a frontend does not publish a hint for a construct, the Studio MUST NOT synthesize one.
## Rationale
This decision separates semantic ownership from host rendering responsibility in the same disciplined way already adopted for frontend semantic presentation.
The chosen split avoids two failure modes:
1. Studio-owned hint content, which would duplicate frontend semantics and make the editor a second semantic authority;
2. frontend-specific rendering logic inside the Studio host, which would make the editor harder to generalize and maintain.
The decision also prevents a common product regression: shipping an approximate overlay and silently letting it become the permanent implementation.
By locking inline real rendering as the required final state, the repository preserves the intended UX target while still allowing phased execution.
Decorative-only hints keep the document model stable and avoid corrupting editing semantics.
Partial degradation tolerance follows the same operational direction already desired for editor highlighting: valid local semantic signal should survive even when the full-document analysis path is degraded.
## Technical Specification
### 1. Capability Model
The editor hint system MUST be implemented as a host capability named conceptually equivalent to inline or inlay hints.
That capability MUST be host-generic and MUST NOT be modeled as a PBS-only feature.
### 2. Ownership Boundary
Frontend responsibilities:
- define whether a hint exists;
- define the semantic meaning of the hint;
- define the anchor location or anchor span;
- define the payload required for rendering, including display text and any semantic category needed by the contract.
LSP responsibilities:
- define the DTO and transport contract consumed by the Studio;
- validate and transport frontend-produced hint payloads;
- preserve enough anchoring information for deterministic host rendering;
- avoid inventing host-owned semantic meaning not present in frontend-produced hint data.
Studio responsibilities:
- render transported hints;
- apply host styling and layout behavior;
- keep hints visually separate from document text;
- preserve editor document semantics and editing behavior.
### 3. Content Policy
The Studio MUST treat hint presence as frontend-authoritative.
The Studio MUST render valid transported hints regardless of the frontend that produced them.
The Studio MUST NOT hardcode rules such as:
- hint all `let` declarations by host policy;
- suppress frontend-provided hints because the host prefers a different policy;
- create fallback semantic hints not present in the contract.
### 4. Rendering Model
The feature is only considered complete when hints are rendered inline in the editor flow as non-textual host decorations attached to document positions.
An approximate visual stage MAY exist temporarily if needed to de-risk delivery, but:
- it MUST be documented as transitional;
- it MUST NOT redefine the final contract;
- subsequent plans MUST converge explicitly to real inline rendering.
### 5. Interaction Model
Hints are decorative only.
Therefore the implementation MUST ensure:
- persisted source text remains unchanged;
- selection ranges are computed over document text only;
- caret movement is computed over document text only;
- copy/paste operates on document text only;
- hint visibility does not alter the canonical file buffer.
### 6. Partial Degradation
When semantic analysis yields only partial valid hint data:
- valid hint spans MUST continue to render;
- invalid or missing spans MAY be omitted locally;
- the Studio MUST NOT disable all hints for the entire document solely because some hint spans could not be produced.
### 7. Initial Scope
This decision is initiated by the PBS need to show inferred type hints for local bindings such as `let`.
However, this decision does not lock hint eligibility to `let`.
Eligibility remains frontend-owned under the contract above.
### 8. Propagation Targets
This decision MUST be propagated to:
- Studio editor specifications covering editor rendering and semantic read surfaces;
- LSP specifications or contracts covering semantic transport payloads;
- implementation plans for frontend hint payload production, LSP transport, and Studio rendering;
- tests covering decorative behavior, anchor stability, partial degradation, and frontend-owned hint policy.
## Constraints
- No implementation plan may reinterpret Studio as semantic owner of hint content.
- No implementation plan may treat an approximate overlay as the final shipped architecture.
- No implementation plan may allow hints to become part of the editable document text model.
- If a later plan discovers that the current editor substrate cannot support inline real rendering cleanly, that plan MUST surface the substrate limitation explicitly and propose the required editor primitive or migration path rather than silently downgrading the final requirement.
## Revision Log
- 2026-04-03: Initial accepted decision from AGD-0018.

125
discussion/workflow/decisions/DEC-0019-studio-frontend-editor-write-and-save-wave.md
View File

@ -1,125 +0,0 @@
---
id: DEC-0019
discussion: DSC-0021
agenda: AGD-0022
ticket: studio-frontend-editor-write-and-save-wave
title: Enable Frontend Editing and Save in the Studio Code Editor
status: accepted
created: 2026-04-04
updated: 2026-04-04
owner: studio
tags: [studio, editor, frontend, write, save, vfs, lsp, pbs, access-policy]
---
## Context
Studio already provides frontend semantic-read value through `prometeu-lsp`, while frontend documents remain hard `read-only`.
The repository also already locked the architectural split between document ownership and semantic ownership:
1. `prometeu-vfs` owns document classification, access mode, snapshots, and save behavior;
2. `prometeu-lsp` consumes VFS-backed snapshots for semantic analysis;
3. Studio UI consumes both boundaries and must not re-derive document rights locally.
The previous semantic-read wave explicitly stated that frontend editing requires a separate decision.
This decision closes that gap.
## Decision
Studio SHALL release frontend editing and frontend save together in one explicit write wave.
The wave is normatively defined as follows:
1. Frontend editing MUST NOT be released without frontend save in the same wave.
2. `prometeu-vfs` MUST remain the sole owner of frontend writable snapshots.
3. `prometeu-vfs` MUST remain the sole owner of frontend access mode.
4. `prometeu-vfs` MUST remain the sole owner of frontend dirty tracking.
5. `prometeu-vfs` MUST remain the sole owner of frontend save and save-all behavior.
6. Studio UI MUST consume frontend editability and save rights from `prometeu-vfs` rather than introducing editor-local policy.
7. `prometeu-lsp` MUST continue as a semantic consumer of VFS-backed frontend snapshots, including dirty in-memory frontend state.
8. This decision does NOT authorize a new LSP implementation wave as part of the immediate execution scope.
9. The first frontend write wave MUST apply to all frontend-scoped supported files and MUST NOT introduce an additional narrowing rule in this wave.
10. Releasing frontend editing MUST NOT collapse semantic ownership, document ownership, and persistence ownership into one module.
## Rationale
Frontend mutation without frontend save would create a half-owned editorial state and weaken the document boundary that the repository has already stabilized.
The correct release shape is therefore coherent FE mutation plus coherent FE persistence under the same owner.
Keeping `prometeu-vfs` as the sole owner preserves the existing architecture:
- VFS owns documents and persistence;
- LSP consumes document state for semantics;
- UI renders and interacts with policy.
This decision also avoids using a fake transitional step where the editor mutates frontend text locally while persistence remains undefined.
## Technical Specification
### Frontend Document Ownership
Frontend-scoped supported files MUST move from hard `read-only` to editable only through `prometeu-vfs`.
That means:
1. writable FE in-memory snapshots MUST be created and owned by VFS;
2. FE dirty tracking MUST be owned by VFS;
3. FE save and save-all MUST route through VFS;
4. editor-visible FE access mode MUST be surfaced from VFS.
### Editor Behavior
The Studio editor MUST consume the new FE access policy from VFS exactly as it already does for non-frontend editable documents.
The editor MUST NOT:
1. create a separate FE-only mutation model;
2. implement FE-local persistence outside VFS;
3. infer FE save rights through UI heuristics.
### LSP Consumption Boundary
`prometeu-lsp` remains authorized to consume dirty FE snapshots from VFS.
However, this decision does not authorize a new LSP feature wave as part of immediate execution.
Immediate implementation may rely on the existing semantic-read seam, provided that:
1. no new persistence ownership moves into LSP;
2. no new access-policy ownership moves into LSP;
3. FE write enablement does not depend on introducing a new LSP-owned document model.
### Scope of First FE Write Wave
The first FE write wave applies to all frontend-scoped supported files currently recognized by the VFS/frontend boundary.
This decision does not authorize:
1. a temporary subset of FE file classes;
2. an editor-only FE draft mode;
3. FE edit rights without FE save rights.
## Constraints
1. This decision does not authorize a new LSP implementation scope by itself.
2. This decision does not authorize moving document state ownership into Studio UI.
3. This decision does not authorize moving document state ownership into LSP.
4. This decision does not authorize releasing FE editing through a separate temporary persistence path.
## Propagation Targets
- Specs:
- `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`
- Plans:
- FE VFS write/access/save propagation
- Studio FE editor access-mode and save UX propagation
- Code:
- `prometeu-vfs` FE writable snapshot and save policy
- `prometeu-studio` FE editor write UX and access-state propagation
- Tests:
- FE VFS access-mode and save coverage
- FE editor editable/saveable behavior
## Revision Log
- 2026-04-04: Accepted from `AGD-0022` to release FE editing and save together under VFS ownership, with no new immediate LSP implementation scope.

137
discussion/workflow/plans/PLN-0030-studio-active-container-and-active-scope-gutter-wave-1.md
View File

@ -1,137 +0,0 @@
---
id: PLN-0030
ticket: studio-editor-scope-guides-and-brace-anchoring
title: Wave 1 editor implementation for active container and active scope gutter indicators
status: done
created: 2026-04-03
completed: 2026-04-03
tags:
- studio
- editor
- scope-guides
- gutter
- active-scope
---
## Objective
Implement the first Studio editor wave mandated by DEC-0014: a gutter-based active-structure indicator that renders at most two simultaneous states, `activeContainer` and `activeScope`, computed locally from existing structural ranges.
## Background
The current editor renders a stacked multi-guide gutter model derived from document symbols. DEC-0014 replaces that default with a constrained active-state presentation:
- keep scope indicators in the gutter;
- compute `activeScope` as the smallest structural range containing the caret;
- compute `activeContainer` as the immediate ancestor of `activeScope`;
- render at most two indicators;
- keep concrete styling frontend-owned.
This plan intentionally covers only the editor-local behavior that can ship without structural-anchor metadata.
## Scope
### Included
- Replace the default stacked guide presentation with an active-state model in `prometeu-studio`.
- Extend the editor scope guide model so it can resolve `activeScope` and `activeContainer` from the caret offset.
- Update gutter rendering to draw no more than two structural indicators.
- Expose semantic slots or equivalent rendering states that allow presentation to distinguish container versus scope.
- Add tests for active-scope selection and active-container selection.
### Excluded
- Exact anchor positioning from structural metadata.
- Changes to frontend payload schemas.
- Changes to semantic read transport contracts outside what the editor already consumes.
## Execution Steps
### Step 1 - Refactor the local scope-guide model around structural containment
**What:** Introduce a model capable of resolving structural containment from caret position and expressing the two active semantic states.
**How:** Update `EditorDocumentScopeGuideModel` so it retains enough structural information to:
- map paragraph and caret offsets back to containing structural ranges;
- select the smallest containing range as `activeScope`;
- select the immediate parent as `activeContainer`;
- expose a paragraph-level view suitable for rendering only the relevant two indicators.
Avoid any logic that promotes higher semantic owners such as function or type when a nearer ancestor exists.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideModel.java`
- supporting editor model classes if extraction improves clarity
### Step 2 - Bind caret movement to active-state recomputation
**What:** Recompute active structural state as the caret moves.
**How:** Update `EditorWorkspace` to observe caret position changes from the `CodeArea`, resolve the current active structural state through the model, and refresh paragraph graphics when the active state changes.
The implementation must remain language-agnostic and rely only on structural ranges already available through the semantic read result.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
### Step 3 - Replace stacked guide rendering with a two-slot gutter renderer
**What:** Redesign the gutter renderer so the default active-state UX shows at most `activeContainer` and `activeScope`.
**How:** Update `EditorDocumentScopeGuideGraphicFactory` to consume the active-state data and render:
- no indicator when no structural range contains the caret;
- one indicator when only `activeScope` exists;
- two distinguishable indicators when both `activeContainer` and `activeScope` exist.
Do not hardcode semantic color contracts into decision logic. The renderer may expose separate style classes, paint roles, or equivalent slots so that presentation styling remains decoupled from the semantic model.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideGraphicFactory.java`
- related editor presentation stylesheet hooks if necessary
### Step 4 - Update editor tests for the new active-state behavior
**What:** Replace tests that validate the old stacked guide model as the default expectation.
**How:** Add or update tests that cover:
- smallest-containing-range selection for `activeScope`;
- immediate-parent selection for `activeContainer`;
- omission of `activeContainer` when no parent exists;
- rendering behavior constrained to at most two semantic indicators.
**File(s):**
- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorDocumentScopeGuideModelTest.java`
- renderer tests or workspace tests if such coverage exists or needs to be introduced
## Test Requirements
### Unit Tests
- Model tests for nested ranges and caret placement transitions.
- Tests that prove immediate-parent selection rather than semantic-owner promotion.
- Tests that prove no more than two semantic gutter indicators are active at once.
### Integration Tests
- Editor workspace tests that move the caret through nested structures and validate gutter state transitions if an existing JavaFX/editor harness is available.
### Manual Verification
- Open a frontend-backed document with nested scopes.
- Move the caret across siblings, parent blocks, and root-level declarations.
- Confirm that the gutter shows only `activeScope` and optional `activeContainer`.
- Confirm that no full ancestry stack is shown by default.
## Acceptance Criteria
- [x] The default editor gutter no longer renders the old full stacked active-scope presentation.
- [x] `activeScope` is selected as the smallest structural range containing the caret.
- [x] `activeContainer` is selected as the immediate structural ancestor of `activeScope`.
- [x] The editor renders at most two active semantic indicators in the gutter.
- [x] The implementation remains language-agnostic and uses only existing structural ranges.
## Dependencies
- Accepted decision `DEC-0014-studio-editor-active-scope-and-structural-anchors.md`
- Existing semantic range payloads already consumed by `EditorWorkspace`
## Risks
- Paragraph-graphic refreshes may become visually noisy or too expensive if caret updates are not throttled or diffed.
- Existing tests may encode the previous stacked-gutter behavior and need coordinated updates.
- The current model may need deeper refactoring than expected if it stores only per-line segments and not enough structural identity information.

112
discussion/workflow/plans/PLN-0031-studio-structural-anchor-semantic-surface-specification.md
View File

@ -1,112 +0,0 @@
---
id: PLN-0031
ticket: studio-editor-scope-guides-and-brace-anchoring
title: Structural anchor semantic surface specification for Studio semantic read
status: done
created: 2026-04-03
completed: 2026-04-03
tags:
- studio
- specs
- semantic-read
- structural-anchors
- frontend-contract
---
## Objective
Specify the dedicated semantic surface required by DEC-0014 for structural anchors and guide-specific structural metadata, without overloading `documentSymbols`.
## Background
DEC-0014 requires exact guide anchoring to come from frontend-owned structural metadata expressed as generic structural anchors. The decision explicitly forbids treating local text scanning as the final contract and explicitly keeps `documentSymbols` as the outline/navigation surface.
This plan covers the normative documentation and contract-shaping work needed before frontend payloads and Studio consumers can converge on a stable schema.
## Scope
### Included
- Define the semantic-read contract boundary for structural anchors in Studio specs.
- Specify a dedicated surface for structural guide metadata separate from `documentSymbols`.
- Define the normative semantics of structural ranges, parentage, and anchors in language-agnostic terms.
- Define how the Studio editor consumes that surface for exact guide start/end anchoring.
### Excluded
- Frontend implementation of the new payload.
- Studio code changes that consume the new payload.
- Theme or visual styling decisions.
## Execution Steps
### Step 1 - Update the semantic-read specification with a dedicated structural-anchor surface
**What:** Add a normative section to the Studio semantic-read specification defining a new dedicated semantic surface for guide-oriented structural metadata.
**How:** Update the semantic-read spec to state that:
- `documentSymbols` remains the outline/navigation surface;
- structural guide metadata is delivered through a separate payload or surface;
- the surface must support structural ranges, parent/child relations when required, and exact anchors for guide rendering;
- the contract is language-agnostic and must not encode brace-only assumptions.
**File(s):**
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
### Step 2 - Update the Code Editor workspace specification for active indicators and anchor consumption
**What:** Propagate DEC-0014 into the Code Editor workspace specification.
**How:** Update the editor spec so it normatively states:
- the gutter remains the primary scope-indicator surface for the initial wave;
- the editor renders at most two active indicators: `activeContainer` and `activeScope`;
- exact start/end anchoring depends on the structural-anchor semantic surface;
- concrete visual treatment remains frontend-owned.
**File(s):**
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
### Step 3 - Define the schema and semantic invariants of structural anchors
**What:** Describe the minimum schema and invariants needed for frontend and Studio implementations to interoperate safely.
**How:** Specify, at minimum:
- what a structural range represents;
- how parentage is expressed or inferred;
- what anchor positions represent;
- how the model behaves for languages with braces, keywords, indentation, or mixed delimiters;
- which invariants tests and future implementations must honor.
If a separate schema subsection or appendix is needed, add it within the relevant spec surface rather than inventing an ad hoc note.
**File(s):**
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
- `docs/specs/studio/5. Code Editor Workspace Specification.md` if editor-facing invariants need reiteration
## Test Requirements
### Unit Tests
- Not applicable at this spec-only stage.
### Integration Tests
- Not applicable at this spec-only stage.
### Manual Verification
- Review the spec text against DEC-0014 and confirm every normative requirement is represented.
- Confirm the spec does not overload `documentSymbols`.
- Confirm the spec speaks in generic structural anchors rather than brace-specific terms.
## Acceptance Criteria
- [x] The semantic-read spec defines a dedicated structural-anchor surface separate from `documentSymbols`.
- [x] The Code Editor spec reflects the two-indicator gutter model and frontend-owned presentation.
- [x] The contract is language-agnostic and does not assume braces as the only structural delimiter.
- [x] The spec text is sufficient for a frontend and Studio implementation plan without reopening DEC-0014.
## Dependencies
- Accepted decision `DEC-0014-studio-editor-active-scope-and-structural-anchors.md`
- Existing Studio specs in `docs/specs/studio`
## Risks
- Over-specifying serialization too early may constrain future frontends unnecessarily.
- Under-specifying parentage and anchor semantics may leave ambiguous implementation choices and force a decision revisit.

126
discussion/workflow/plans/PLN-0032-frontend-structural-anchor-payloads-and-anchor-aware-tests.md
View File

@ -1,126 +0,0 @@
---
id: PLN-0032
ticket: studio-editor-scope-guides-and-brace-anchoring
title: Frontend structural-anchor payload propagation and anchor-aware test coverage
status: done
created: 2026-04-03
completed: 2026-04-03
tags:
- studio
- frontend
- semantic-read
- structural-anchors
- tests
---
## Objective
Implement and validate frontend-produced structural-anchor payloads and the Studio-side test coverage required to support exact anchor-aware gutter rendering after the contract defined in DEC-0014 and its derived specs is in place.
## Background
DEC-0014 splits execution into two tracks:
- a first local editor wave based on existing structural ranges;
- a later exact-anchoring wave backed by frontend-owned structural metadata delivered through a dedicated semantic surface.
This plan covers the propagation work after the semantic surface is specified.
## Scope
### Included
- Extend the relevant frontend semantic-read payloads to emit structural-anchor metadata.
- Extend Studio-side DTOs or semantic-read consumption models to accept the new payload.
- Add tests proving that exact anchor positions survive transport and can drive guide rendering.
- Validate language-agnostic behavior through contract-level fixtures or tests.
### Excluded
- The first-wave active-container/active-scope editor behavior based only on current ranges.
- Broader presentation redesign beyond what is required to consume exact anchors.
## Execution Steps
### Step 1 - Extend frontend semantic-read producers with structural-anchor payloads
**What:** Add production of the dedicated structural-anchor surface in the relevant frontend(s).
**How:** For each participating frontend, emit:
- structural ranges;
- parentage or equivalent ancestry data as required by the final spec;
- anchor positions for exact guide start/end rendering.
Implementations must honor the language-agnostic contract while mapping language-specific structure into the generic anchor model.
**File(s):**
- frontend semantic-read producers and payload mappers, to be identified from the accepted spec work
### Step 2 - Extend Studio semantic-read consumption models
**What:** Teach Studio DTOs and semantic-read consumption code to accept the structural-anchor surface.
**How:** Update DTOs, transport mapping, and editor-side analysis models so the new structural metadata can flow from semantic read results into the gutter renderer without polluting `documentSymbols`.
**File(s):**
- Studio DTO and semantic-read integration modules, to be identified after schema finalization
- `prometeu-studio` editor integration points that consume semantic analysis results
### Step 3 - Make gutter rendering anchor-aware
**What:** Upgrade the gutter renderer to use exact structural anchors when available.
**How:** Adapt the active indicator renderer so guide start/end/cap placement uses structural-anchor metadata rather than symbol-line midpoint approximations.
The implementation must preserve the DEC-0014 rule that structural anchors are the canonical source of exact positioning.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideGraphicFactory.java`
- associated editor model or adapter layers introduced to consume structural anchors
### Step 4 - Add anchor-aware contract and rendering tests
**What:** Add tests covering transport, interpretation, and rendering of structural anchors.
**How:** Introduce tests that prove:
- structural-anchor payloads are emitted by frontend semantic read;
- Studio receives and stores them separately from `documentSymbols`;
- exact opening/closing anchor positions drive rendering behavior;
- languages with non-brace structure can still map into the generic contract.
**File(s):**
- frontend semantic-read tests
- Studio DTO/transport tests
- editor model and renderer tests
## Test Requirements
### Unit Tests
- Payload schema mapping tests.
- Editor adapter/model tests for anchor interpretation.
- Renderer tests for exact start/end placement using anchor positions.
### Integration Tests
- End-to-end semantic-read tests from frontend producer to Studio consumer when an existing harness supports that boundary.
### Manual Verification
- Open representative nested documents after structural anchors are available.
- Confirm that guide start/end visually align with structural anchor positions rather than line midpoints.
- Confirm that the active indicator model remains limited to `activeContainer` and `activeScope`.
## Acceptance Criteria
- [x] Frontend semantic-read payloads expose structural anchors through a dedicated semantic surface.
- [x] Studio consumes structural anchors without overloading `documentSymbols`.
- [x] Exact guide positioning uses structural-anchor metadata when available.
- [x] Tests cover payload transport, anchor interpretation, and anchor-aware rendering.
## Dependencies
- Accepted decision `DEC-0014-studio-editor-active-scope-and-structural-anchors.md`
- Accepted spec work derived from `PLN-0031`
- Studio editor wave-1 implementation from `PLN-0030` if shared gutter machinery is reused
## Risks
- Frontend payload evolution may require coordinated versioning or backwards-compatibility handling.
- Test fixtures may become brittle if the structural-anchor schema is not stabilized before implementation starts.
- Exact rendering behavior may vary with font metrics and paragraph layout, requiring robust assertions that test semantic placement rather than pixel-perfect incidental details.

103
discussion/workflow/plans/PLN-0033-inline-hint-spec-and-contract-propagation.md
View File

@ -1,103 +0,0 @@
---
id: PLN-0033
ticket: studio-editor-inline-type-hints-for-let-bindings
title: Inline hint specification and contract propagation
status: done
created: 2026-04-03
completed: 2026-04-03
tags: [studio, editor, specs, inline-hints, lsp, frontend-contract]
---
## Objective
Propagate DEC-0015 into the normative specification surfaces that define editor responsibilities, LSP semantic-read transport, and compiler/frontend contract authority for inline hints.
## Background
DEC-0015 locks inline hints as a host-generic editor capability with frontend-defined payloads, LSP-enforced transport, Studio rendering, decorative-only interaction, and partial-degradation preservation. No implementation plan may weaken those rules by inference.
The repository already has normative surfaces for editor behavior, semantic-read transport, and frontend-owned semantic contracts. Those surfaces must be updated before implementation splits across LSP, PBS, and Studio code.
## Scope
### Included
- Propagate DEC-0015 to Studio editor specs.
- Propagate DEC-0015 to integrated semantic-read specs.
- Extend compiler/frontend contract language where needed so frontend-owned hint metadata has a stable authority surface.
- Define the normative distinction between transitional approximation and final inline rendering.
### Excluded
- LSP DTO implementation.
- PBS hint payload production.
- Studio rendering code.
## Execution Steps
### Step 1 - Update the Code Editor workspace specification for inline hint rendering
**What:** Add normative editor requirements for decorative inline hints, host responsibilities, and inline-real final rendering.
**How:** Update the Studio Code Editor specification to state that:
- inline hints are host-generic editor capabilities;
- hint content remains frontend-owned;
- the editor renders but does not invent hints;
- hints are decorative only and do not alter text, selection, caret movement, or persistence;
- a transitional approximate stage may exist only as an explicit rollout step;
- the final completed capability is real inline rendering.
**File(s):**
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
### Step 2 - Update the semantic-read phase specification for inline hint transport
**What:** Define inline hint transport as part of the semantic-read contract.
**How:** Update the semantic-read specification so it normatively states:
- inline/inlay hints are frontend-owned semantic payloads transported through `prometeu-lsp`;
- LSP owns the DTO and transport contract but not hint semantics;
- valid hint spans must survive partial degradation;
- the transport must preserve deterministic anchor information needed by Studio rendering.
**File(s):**
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
### Step 3 - Update compiler/frontend contract authority for frontend-owned hint metadata
**What:** Extend the compiler/frontend contract language so frontend-owned editor hint metadata has an explicit authority surface parallel to semantic presentation.
**How:** Update the compiler entrypoint/frontend contract specification to state that `FrontendSpec` or an equivalent accepted frontend-owned semantic contract surface remains the canonical source for static hint contract metadata when such metadata is required by downstream consumers.
The text must not imply Studio-owned or LSP-owned semantic hint policy.
**File(s):**
- `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md`
## Test Requirements
### Unit Tests
- Not applicable for this spec-only plan.
### Integration Tests
- Not applicable for this spec-only plan.
### Manual Verification
- Review the updated specs against DEC-0015 and confirm all normative points are represented.
- Confirm the final-state requirement still says inline real rendering.
- Confirm the specs do not give Studio authority over hint existence or content.
## Acceptance Criteria
- [x] Studio editor specs define inline hints as decorative, host-generic, and final-state inline real.
- [x] Semantic-read specs define frontend-owned hint transport and partial-degradation preservation.
- [x] Compiler/frontend contract language preserves frontend ownership of hint semantics.
- [x] The specification set is sufficient for code plans without reopening DEC-0015.
## Dependencies
- Accepted decision `DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md`
- Existing Studio and compiler specifications.
## Risks
- Under-specifying the contract may force DTO churn later.
- Overloading existing semantic presentation wording may blur the distinction between static presentation metadata and dynamic hint payload transport.

107
discussion/workflow/plans/PLN-0034-lsp-inline-hint-transport-contract.md
View File

@ -1,107 +0,0 @@
---
id: PLN-0034
ticket: studio-editor-inline-type-hints-for-let-bindings
title: LSP inline hint transport contract
status: done
created: 2026-04-03
completed: 2026-04-03
tags: [lsp, studio, editor, inline-hints, dto, transport]
---
## Objective
Implement the LSP transport contract that enforces and delivers frontend-owned inline hint payloads to Studio consumers.
## Background
DEC-0015 requires the LSP to fix and transport the inline hint contract while preserving frontend ownership of hint content and anchor semantics. The Studio must consume transported hints mechanically, and valid spans must survive partial degradation.
Current LSP surfaces carry diagnostics, symbols, structural anchors, and semantic highlighting, but no dedicated inline hint payload.
## Scope
### Included
- Add a dedicated inline hint DTO/message surface to `prometeu-lsp-api`.
- Extend semantic session and analyze-result transport to include inline hint payloads.
- Ensure partial valid hints survive transport even when analysis is partially degraded.
- Add LSP tests for contract shape and partial preservation.
### Excluded
- Frontend production of hint payloads.
- Studio rendering.
- Final editor substrate changes.
## Execution Steps
### Step 1 - Define public DTOs for inline hint payloads
**What:** Add public API DTOs/messages for inline hint transport.
**How:** Introduce explicit payload shapes in `prometeu-lsp-api` that cover at minimum:
- anchor location or anchor span;
- display text;
- optional semantic category/styling fields if required by the contract;
- enough information for decorative-only host rendering.
The contract must remain frontend-content-preserving and must not encode Studio-owned hint policy.
**File(s):**
- `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/dtos/`
- `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/messages/`
### Step 2 - Extend semantic session construction and analyze responses
**What:** Make `prometeu-lsp-v1` collect and return inline hints in the semantic-read result.
**How:** Update semantic session building and analyze-result assembly so inline hints are returned alongside diagnostics, symbols, structural anchors, and semantic highlights.
Transport must preserve valid hint payloads even if some hint production fails locally elsewhere in the same document.
**File(s):**
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspSemanticReadPhase.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspSemanticAnalyseService.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/`
### Step 3 - Add transport contract tests
**What:** Lock the LSP contract behavior with focused tests.
**How:** Add tests that verify:
- analyze responses can carry inline hints;
- hint payloads preserve anchors and text deterministically;
- valid hints survive partial degradation;
- no host-owned inference is inserted by the LSP when the frontend does not publish hints.
**File(s):**
- `prometeu-lsp/prometeu-lsp-v1/src/test/java/p/studio/lsp/`
- `prometeu-lsp/prometeu-lsp-api/src/test/java/` if DTO/API conformance tests are needed
## Test Requirements
### Unit Tests
- DTO invariants for inline hint payloads.
- Session/result assembly tests for non-empty and empty hint payloads.
### Integration Tests
- Analyze-document tests covering partial valid hints under degraded analysis.
### Manual Verification
- Inspect serialized/analyzed LSP results for a PBS document with inferred `let` types.
- Confirm no hint appears when the frontend publishes none.
## Acceptance Criteria
- [x] `prometeu-lsp-api` exposes a dedicated inline hint transport contract.
- [x] `prometeu-lsp-v1` returns inline hints through analyze results without inventing content.
- [x] Partial valid hints survive transport under degraded analysis.
- [x] Tests lock the contract shape and preservation rules.
## Dependencies
- Accepted decision `DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md`
- `PLN-0033-inline-hint-spec-and-contract-propagation.md`
## Risks
- DTO under-design may force churn once Studio rendering starts.
- Folding inline hints into an existing message surface without clear boundaries may create avoidable API ambiguity.

110
discussion/workflow/plans/PLN-0035-pbs-inline-type-hint-payload-production.md
View File

@ -1,110 +0,0 @@
---
id: PLN-0035
ticket: studio-editor-inline-type-hints-for-let-bindings
title: PBS inline type hint payload production
status: done
created: 2026-04-03
completed: 2026-04-03
tags: [compiler, pbs, inline-hints, type-inference, lsp]
---
## Objective
Produce frontend-owned inline hint payloads for PBS inferred local bindings, starting with `let` bindings whose types are omitted in source.
## Background
DEC-0015 explicitly leaves hint eligibility frontend-owned. The initial user need comes from PBS inferred `let` bindings, and PBS already computes the inferred type during flow analysis. That semantic fact now needs to be surfaced as frontend-produced hint payload rather than remaining internal-only analysis state.
## Scope
### Included
- Surface PBS-produced inline type hints for inferred `let` bindings.
- Reuse existing flow-analysis type information rather than adding parallel inference.
- Preserve valid hints under partial degradation wherever the frontend can still produce them.
- Add PBS/LSP-facing tests for hint eligibility and payload correctness.
### Excluded
- Host rendering policy.
- Non-PBS frontend hint production.
- Hint categories not chosen by PBS.
## Execution Steps
### Step 1 - Identify stable anchor and payload sources in PBS analysis
**What:** Determine the exact PBS semantic source for inferred binding type and anchor location.
**How:** Trace `let` analysis through the PBS flow-analysis pipeline and identify:
- where inferred local binding type becomes stable;
- how to render that type as display text;
- which source position should anchor the hint;
- what happens when the binding has explicit type text and therefore should not receive an inferred-type hint.
This step must avoid recomputing types outside the existing semantic pipeline.
**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/`
### Step 2 - Emit frontend-owned hint payloads for eligible bindings
**What:** Make PBS produce inline hint payloads for eligible inferred bindings.
**How:** Extend the PBS semantic-read production path so it emits frontend-owned hint entries for `let` bindings with omitted type syntax and stable inferred type results.
The production path must:
- suppress hints when PBS does not want one;
- avoid emitting hints for explicitly typed bindings;
- preserve valid hints even if unrelated parts of the document degrade.
**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/`
- any accepted frontend semantic contract surface used by `prometeu-lsp`
### Step 3 - Add PBS-focused hint production tests
**What:** Lock PBS hint policy and payload behavior with tests.
**How:** Add tests for:
- inferred `let` bindings receiving hints;
- explicit `let name: Type = ...` bindings receiving no inferred-type hint;
- payload text stability for scalar, struct, optional, result, tuple, or other supported type forms chosen by PBS;
- partial-degradation cases where unaffected bindings still produce hints.
**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/`
- `prometeu-lsp/prometeu-lsp-v1/src/test/java/p/studio/lsp/` where end-to-end analyze assertions are required
## Test Requirements
### Unit Tests
- PBS semantic tests for inferred binding hint eligibility.
- Type-surface formatting tests if payload display text is factored into a helper.
### Integration Tests
- LSP analyze tests verifying PBS-produced hints appear in transported results.
- Partial-degradation tests preserving unaffected hints.
### Manual Verification
- Open a PBS document with inferred `let` bindings and inspect the LSP analyze payload.
- Confirm no hints appear for explicit type annotations.
## Acceptance Criteria
- [ ] PBS produces frontend-owned inline hint payloads for eligible inferred `let` bindings.
- [ ] Explicitly typed bindings do not receive inferred-type hints.
- [ ] Valid hints survive unrelated local degradation when PBS can still analyze those bindings.
- [ ] Tests lock the frontend-owned eligibility policy.
## Dependencies
- Accepted decision `DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md`
- `PLN-0033-inline-hint-spec-and-contract-propagation.md`
- `PLN-0034-lsp-inline-hint-transport-contract.md`
## Risks
- If inferred-type display text is not normalized, hint output may become unstable across equivalent semantic forms.
- If hint production is attached too late in the pipeline, degraded documents may lose more valid hints than necessary.

127
discussion/workflow/plans/PLN-0036-studio-inline-hint-rendering-and-rollout.md
View File

@ -1,127 +0,0 @@
---
id: PLN-0036
ticket: studio-editor-inline-type-hints-for-let-bindings
title: Studio inline hint rendering and rollout
status: done
created: 2026-04-03
completed: 2026-04-03
tags: [studio, editor, inline-hints, rendering, rollout, richtextfx]
---
## Objective
Implement the Studio host rendering path for transported inline hints, including any explicit transitional stage and convergence to real inline rendering.
## Background
DEC-0015 requires the final user-visible capability to be real inline rendering in the editor flow. A transitional approximate stage is allowed only if explicitly treated as a rollout stage and not as the final architecture. Hints must remain decorative and must survive partial valid spans under degraded analysis.
The current editor uses `CodeArea` with `StyleSpans`, gutter graphics, and semantic overlays, which is sufficient for color and gutter behavior but not obviously sufficient for true inline non-text decorations without substrate work.
## Scope
### Included
- Add a Studio host rendering path for transported inline hints.
- Preserve decorative-only behavior.
- Preserve valid hints under partial degradation.
- If needed, implement an explicit transitional rendering wave and a follow-up convergence step to real inline rendering.
- Add editor tests for rendering behavior and document-model isolation.
### Excluded
- Frontend hint eligibility policy.
- LSP transport contract design.
- Non-editor consumers of hint payloads.
## Execution Steps
### Step 1 - Evaluate and choose the editor substrate for real inline rendering
**What:** Determine the exact editor primitive needed to support true inline hint rendering.
**How:** Evaluate the current `CodeArea`-based surface and decide whether real inline hints can be supported by extension or require a migration to a richer editor substrate.
This step must explicitly document:
- why the chosen substrate can satisfy the decision;
- whether a transitional approximation is required;
- what migration path exists if the current substrate is insufficient.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/`
- any editor utility or custom rendering surfaces introduced by the chosen approach
### Step 2 - Implement decorative host rendering for transported hints
**What:** Render LSP-transported hints in the editor without mutating document text.
**How:** Add a host rendering layer that:
- consumes inline hint payloads from analyze results;
- renders them at deterministic anchors;
- keeps them out of the persisted text model;
- keeps caret, selection, copy/paste, and editing semantics text-only.
If a transitional approximation is required, it must be explicitly isolated and labeled as wave 1 rather than as final architecture.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/`
- `prometeu-studio/src/main/resources/themes/` if hint-specific host styling is needed
### Step 3 - Converge to real inline rendering if wave 1 is approximate
**What:** Ensure the implementation reaches the decision-mandated final state.
**How:** If step 2 introduces an approximate rendering wave, add the explicit follow-up work needed to move to true inline rendering and retire the approximation.
This convergence work must not be left implicit.
**File(s):**
- the same editor rendering surfaces chosen in steps 1 and 2
### Step 4 - Add Studio rendering and interaction tests
**What:** Lock decorative behavior and partial-degradation rendering in Studio tests.
**How:** Add tests that verify:
- hints render when transported;
- hints do not modify the text buffer;
- hints do not become part of copy/paste semantics;
- valid hints remain visible even when only some hint spans are available;
- the final path uses real inline rendering once the convergence step is complete.
**File(s):**
- `prometeu-studio/src/test/java/p/studio/workspaces/editor/`
## Test Requirements
### Unit Tests
- Rendering-layer tests for anchor mapping and decorative-only behavior.
- Tests ensuring text buffer content remains unchanged.
### Integration Tests
- Editor tests consuming analyze results with inline hints.
- Partial-degradation tests preserving valid hint spans.
- Convergence tests for the final inline-real path if a transitional wave exists.
### Manual Verification
- Open a PBS file with inferred `let` bindings and confirm hints render next to the binding without entering the file text.
- Confirm cursor movement and copy/paste ignore hint text.
- Confirm partially valid hints remain visible when some bindings fail analysis.
## Acceptance Criteria
- [ ] Studio can render transported inline hints without mutating document text.
- [ ] Decorative-only interaction rules are enforced.
- [ ] Partial valid hints remain visible under degraded analysis.
- [ ] If a transitional approximation exists, the path to real inline rendering is explicitly implemented and not left as implied follow-up.
## Dependencies
- Accepted decision `DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md`
- `PLN-0033-inline-hint-spec-and-contract-propagation.md`
- `PLN-0034-lsp-inline-hint-transport-contract.md`
- `PLN-0035-pbs-inline-type-hint-payload-production.md`
## Risks
- The current editor substrate may not support inline-real rendering cleanly without deeper refactoring.
- A temporary approximation may linger unless the convergence step is explicitly tracked and executed.
- Decorative behavior may be accidentally violated if the rendering layer leaks into text model operations.

175
discussion/workflow/plans/PLN-0040-studio-frontend-editor-write-and-save-wave.md
View File

@ -1,175 +0,0 @@
---
id: PLN-0040
discussion: DSC-0021
decision: DEC-0019
ticket: studio-frontend-editor-write-and-save-wave
title: Implement the frontend editor write and save wave through VFS ownership
status: done
created: 2026-04-04
updated: 2026-04-04
owner: studio
tags: [studio, editor, frontend, write, save, vfs, lsp, pbs, access-policy]
---
## Briefing
Implement the accepted frontend write wave for the Studio Code Editor.
Frontend editing and frontend save must be released together, must remain owned by `prometeu-vfs`, and must be consumed by Studio UI without introducing a new immediate LSP implementation wave.
## Objective
Move frontend-scoped supported files from hard `read-only` to VFS-owned editable/saveable documents while preserving the current boundary:
- `prometeu-vfs` owns document state and persistence;
- `prometeu-lsp` remains a semantic consumer of VFS-backed snapshots;
- Studio UI remains a policy consumer.
## Dependencies
- `DEC-0019` Enable Frontend Editing and Save in the Studio Code Editor
- existing `prometeu-vfs` editable snapshot and save model for non-frontend textual documents
- existing Studio editor consumption of VFS access mode and save behavior
- existing semantic-read seam where `prometeu-lsp` reads VFS-backed frontend snapshots
## Scope
- propagate the new FE write/save contract into Studio and VFS specs
- extend `prometeu-vfs` so frontend-scoped supported files become editable/saveable
- keep FE writable snapshots, dirty tracking, and save ownership inside VFS
- update Studio editor behavior to consume FE editability from VFS
- update FE write/save tests in VFS and Studio
## Non-Goals
- any new LSP feature implementation wave
- per-file FE access policy
- partial FE draft mode without save
- moving persistence logic into Studio UI
- moving persistence logic into `prometeu-lsp`
## Execution Method
### 1. Propagate the accepted contract into specs
Update the Studio specs that still describe FE files as hard `read-only` so they now describe the new FE write/save wave and preserve VFS ownership plus semantic-consumer-only LSP ownership.
Targets:
- `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`
### 2. Change FE access policy in `prometeu-vfs`
Update the filesystem-backed VFS classification so frontend-scoped supported files become `EDITABLE` rather than `READ_ONLY`, while preserving frontend classification itself.
What changes:
- document kind classification for FE files
- VFS acceptance of FE `updateDocument`
- VFS save/save-all behavior for FE snapshots
- FE dirty tracking semantics under the same VFS owner model already used for editable non-frontend documents
Targets:
- `prometeu-vfs/prometeu-vfs-v1/src/main/java/p/studio/vfs/FilesystemVfsProjectDocument.java`
- any supporting VFS API contracts if required by the implementation
Dependency ordering:
- this step must land before Studio editor UX changes so the UI can consume the new policy rather than invent it.
### 3. Update VFS tests for FE edit/save behavior
Replace tests that assert FE hard `read-only` behavior with tests that assert:
1. FE documents open as frontend documents with `EDITABLE` access mode;
2. FE documents accept `updateDocument`;
3. FE documents save correctly through `saveDocument`;
4. FE documents participate correctly in `saveAllDocuments`.
Targets:
- `prometeu-vfs/prometeu-vfs-v1/src/test/java/p/studio/vfs/FilesystemVfsProjectDocumentTest.java`
### 4. Propagate FE editability into the Studio editor
Update the Studio editor to consume the new FE access mode from VFS exactly as it already does for editable non-frontend documents.
What changes:
- FE tabs become editable when VFS reports `EDITABLE`
- FE warning surfaces that are specific to hard `read-only` FE behavior must be revised or removed
- editor save/save-all enablement must work for dirty FE buffers through the existing VFS-backed flow
- no FE-local persistence path may be introduced
Targets:
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorStatusBar.java`
- any FE-warning or editor-session support classes affected by access-mode transition
Dependency ordering:
- this step depends on VFS access-mode propagation from Step 2.
### 5. Keep LSP integration stable without opening new implementation scope
Verify that the existing editor and semantic-read flow still calls `prometeu-lsp` as a consumer of FE snapshots, but do not introduce a new LSP implementation wave.
What changes:
- only compatibility adjustments that are strictly necessary because FE snapshots are now editable may be made;
- no new semantic features, refresh model, or ownership expansion is authorized here.
Targets:
- only the minimum compatibility surface if compilation or existing tests require it
Dependency ordering:
- this is verification-oriented and should follow the VFS/editor write changes.
### 6. Update Studio tests for FE editable/saveable behavior
Add or revise editor tests so they assert FE files are no longer treated as permanently hard `read-only` once VFS grants FE `EDITABLE` access mode.
Targets:
- Studio editor tests under `prometeu-studio/src/test/java/p/studio/workspaces/editor/...`
- any session/editor tests affected by FE access-mode transition
## Acceptance Criteria
1. Frontend-scoped supported files open through VFS with `EDITABLE` access mode.
2. Frontend-scoped supported files can be updated and saved through VFS-owned snapshots.
3. Studio editor FE tabs become editable only because VFS reports them as editable.
4. FE save and save-all route through the same VFS owner path used by other editable documents.
5. No new persistence or access-policy ownership moves into Studio UI.
6. No new persistence or access-policy ownership moves into `prometeu-lsp`.
7. Specs no longer describe FE files as hard `read-only` for the current wave.
## Tests
- VFS tests for FE access mode, update, save, and save-all
- Studio editor tests for FE editable/saveable behavior
- regression tests that confirm non-frontend editable documents still behave correctly
- compile/test verification that existing LSP consumer seams still pass without opening new LSP feature scope
## Affected Artifacts
- `discussion/workflow/decisions/DEC-0019-studio-frontend-editor-write-and-save-wave.md`
- `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-vfs/prometeu-vfs-v1/src/test/java/p/studio/vfs/FilesystemVfsProjectDocumentTest.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/...`
- Studio editor tests
## Risks
- existing specs and tests currently encode the old hard `read-only` FE contract and will fail until all propagation lands coherently
- FE warning/UI surfaces may assume old read-only semantics in more than one place
- LSP snapshot consumption could reveal hidden assumptions about FE immutability even without opening a new LSP scope
- if implementation order is reversed and Studio is changed before VFS policy, UI code may drift into local heuristics