From 38d8c25bbadab219e2a7f21787e09a48e575319e Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Thu, 26 Mar 2026 18:45:46 +0000 Subject: [PATCH] discussion framework migration --- .discussion/index.ndjson | 6 + ...-assets-workspace-execution-wave-legacy.md | 52 ++++++ ...LSN-0002-bank-composition-editor-legacy.md | 47 +++++ ...003-mental-model-asset-mutations-legacy.md | 47 +++++ ...04-mental-model-assets-workspace-legacy.md | 51 ++++++ ...del-studio-events-and-components-legacy.md | 45 +++++ ...N-0006-mental-model-studio-shell-legacy.md | 49 ++++++ .../LSN-0007-pack-wizard-shell-legacy.md | 47 +++++ ...roject-scoped-state-and-activity-legacy.md | 50 ++++++ .../LSN-0016-studio-docs-import-pattern.md | 51 ++++++ .../LSN-0009-mental-model-packer-legacy.md | 44 +++++ ...et-identity-and-runtime-contract-legacy.md | 43 +++++ ...ions-workspace-runtime-and-build-legacy.md | 46 +++++ ...me-ownership-and-studio-boundary-legacy.md | 45 +++++ ...ata-convergence-and-runtime-sink-legacy.md | 44 +++++ ...ry-validation-and-pack-execution-legacy.md | 47 +++++ ...-0015-tile-bank-packing-contract-legacy.md | 46 +++++ .../LSN-0017-packer-docs-import-pattern.md | 50 ++++++ .../AGD-0002-palette-management-in-studio.md | 116 ++++++++++++ ...emap-and-metatile-runtime-binary-layout.md | 97 ++++++++++ ...ariable-tile-bank-palette-serialization.md | 87 +++++++++ docs/compiler/general/README.md | 20 --- docs/compiler/pbs/agendas/README.md | 41 +++-- docs/packer/README.md | 112 ------------ docs/packer/agendas/README.md | 54 ------ ...d Metatile Runtime Binary Layout Agenda.md | 152 ---------------- ... Tile Bank Palette Serialization Agenda.md | 142 --------------- docs/packer/decisions/README.md | 53 ------ docs/packer/learn/README.md | 59 ------- ...foundations-workspace-runtime-and-build.md | 91 ---------- ...del-asset-identity-and-runtime-contract.md | 95 ---------- ...l-metadata-convergence-and-runtime-sink.md | 78 --------- docs/packer/learn/mental-model-packer.md | 87 --------- ...d-summary-validation-and-pack-execution.md | 118 ------------- .../runtime-ownership-and-studio-boundary.md | 88 ---------- .../learn/tile-bank-packing-contract.md | 116 ------------ docs/packer/pull-requests/README.md | 68 -------- .../pbs}/1. Language Charter.md | 0 .../10. Memory and Lifetime Specification.md | 0 .../pbs}/11. AST Specification.md | 0 .../pbs}/12. Diagnostics Specification.md | 0 .../13. Lowering IRBackend Specification.md | 0 .../pbs}/2. Governance and Versioning.md | 0 .../pbs}/3. Core Syntax Specification.md | 0 .../pbs}/4. Static Semantics Specification.md | 0 ...tdlib, and SDK Resolution Specification.md | 0 .../pbs}/6. VM-owned vs Host-backed.md | 0 ...rinsics and Builtin Types Specification.md | 0 ...ing and Loader Resolution Specification.md | 0 ... and Runtime Capabilities Specification.md | 0 ...ent Packaging and Loading Specification.md | 0 .../9. Dynamic Semantics Specification.md | 0 .../compiler-languages/pbs}/README.md | 0 .../13. Conformance Test Specification.md | 0 ...lution and Module Linking Specification.md | 0 ... Bytecode and PBX Mapping Specification.md | 0 ...cution and Initialization Specification.md | 0 .../17. Compatibility and Evolution Policy.md | 0 ... Standard Library Surface Specification.md | 0 ...ication and Safety Checks Specification.md | 0 ...RBackend to IRVM Lowering Specification.md | 0 ...RVM Optimization Pipeline Specification.md | 0 ...Backend Spec-to-Test Conformance Matrix.md | 0 .../specs => specs/compiler}/README.md | 0 ...ain and Artifact Boundary Specification.md | 0 ...istry, and Asset Identity Specification.md | 0 ...nd Virtual Asset Contract Specification.md | 0 ...and Deterministic Packing Specification.md | 0 ...s, and Studio Integration Specification.md | 0 ...igration, and Trust Model Specification.md | 0 docs/{packer/specs => specs/packer}/README.md | 12 +- ...hell and Workspace Layout Specification.md | 0 .../2. Studio UI Foundations Specification.md | 0 ... Studio Components Module Specification.md | 0 .../4. Assets Workspace Specification.md | 6 +- docs/{studio/specs => specs/studio}/README.md | 8 +- docs/studio/README.md | 118 ------------- .../Palette Management in Studio Agenda.md | 165 ------------------ docs/studio/agendas/README.md | 50 ------ docs/studio/decisions/README.md | 49 ------ docs/studio/learn/README.md | 56 ------ .../learn/assets-workspace-execution-wave.md | 88 ---------- docs/studio/learn/bank-composition-editor.md | 126 ------------- .../learn/mental-model-asset-mutations.md | 128 -------------- .../learn/mental-model-assets-workspace.md | 119 ------------- ...ntal-model-studio-events-and-components.md | 76 -------- .../studio/learn/mental-model-studio-shell.md | 60 ------- docs/studio/learn/pack-wizard-shell.md | 87 --------- .../project-scoped-state-and-activity.md | 57 ------ docs/studio/pull-requests/README.md | 46 ----- 90 files changed, 1150 insertions(+), 2585 deletions(-) create mode 100644 .discussion/index.ndjson create mode 100644 .discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md create mode 100644 .discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md create mode 100644 .discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md create mode 100644 .discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md create mode 100644 .discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md create mode 100644 .discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md create mode 100644 .discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md create mode 100644 .discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md create mode 100644 .discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md create mode 100644 .discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md create mode 100644 .discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md create mode 100644 .discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md create mode 100644 .discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md create mode 100644 .discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md create mode 100644 .discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md create mode 100644 .discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md create mode 100644 .discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md create mode 100644 .discussion/workflow/agendas/AGD-0002-palette-management-in-studio.md create mode 100644 .discussion/workflow/agendas/AGD-0004-tilemap-and-metatile-runtime-binary-layout.md create mode 100644 .discussion/workflow/agendas/AGD-0005-variable-tile-bank-palette-serialization.md delete mode 100644 docs/compiler/general/README.md delete mode 100644 docs/packer/README.md delete mode 100644 docs/packer/agendas/README.md delete mode 100644 docs/packer/agendas/Tilemap and Metatile Runtime Binary Layout Agenda.md delete mode 100644 docs/packer/agendas/Variable Tile Bank Palette Serialization Agenda.md delete mode 100644 docs/packer/decisions/README.md delete mode 100644 docs/packer/learn/README.md delete mode 100644 docs/packer/learn/foundations-workspace-runtime-and-build.md delete mode 100644 docs/packer/learn/mental-model-asset-identity-and-runtime-contract.md delete mode 100644 docs/packer/learn/mental-model-metadata-convergence-and-runtime-sink.md delete mode 100644 docs/packer/learn/mental-model-packer.md delete mode 100644 docs/packer/learn/pack-wizard-summary-validation-and-pack-execution.md delete mode 100644 docs/packer/learn/runtime-ownership-and-studio-boundary.md delete mode 100644 docs/packer/learn/tile-bank-packing-contract.md delete mode 100644 docs/packer/pull-requests/README.md rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/1. Language Charter.md (100%) rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/10. Memory and Lifetime Specification.md (100%) rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/11. AST Specification.md (100%) rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/12. Diagnostics Specification.md (100%) rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/13. Lowering IRBackend Specification.md (100%) rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/2. Governance and Versioning.md (100%) rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/3. Core Syntax Specification.md (100%) rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/4. Static Semantics Specification.md (100%) rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/5. Manifest, Stdlib, and SDK Resolution Specification.md (100%) rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/6. VM-owned vs Host-backed.md (100%) rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/6.1. Intrinsics and Builtin Types Specification.md (100%) rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/6.2. Host ABI Binding and Loader Resolution Specification.md (100%) rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/7. Cartridge Manifest and Runtime Capabilities Specification.md (100%) rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/8. Stdlib Environment Packaging and Loading Specification.md (100%) rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/9. Dynamic Semantics Specification.md (100%) rename docs/{compiler/pbs/specs => specs/compiler-languages/pbs}/README.md (100%) rename docs/{compiler/general/specs => specs/compiler}/13. Conformance Test Specification.md (100%) rename docs/{compiler/general/specs => specs/compiler}/14. Name Resolution and Module Linking Specification.md (100%) rename docs/{compiler/general/specs => specs/compiler}/15. Bytecode and PBX Mapping Specification.md (100%) rename docs/{compiler/general/specs => specs/compiler}/16. Runtime Execution and Initialization Specification.md (100%) rename docs/{compiler/general/specs => specs/compiler}/17. Compatibility and Evolution Policy.md (100%) rename docs/{compiler/general/specs => specs/compiler}/18. Standard Library Surface Specification.md (100%) rename docs/{compiler/general/specs => specs/compiler}/19. Verification and Safety Checks Specification.md (100%) rename docs/{compiler/general/specs => specs/compiler}/20. IRBackend to IRVM Lowering Specification.md (100%) rename docs/{compiler/general/specs => specs/compiler}/21. IRVM Optimization Pipeline Specification.md (100%) rename docs/{compiler/general/specs => specs/compiler}/22. Backend Spec-to-Test Conformance Matrix.md (100%) rename docs/{compiler/general/specs => specs/compiler}/README.md (100%) rename docs/{packer/specs => specs/packer}/1. Domain and Artifact Boundary Specification.md (100%) rename docs/{packer/specs => specs/packer}/2. Workspace, Registry, and Asset Identity Specification.md (100%) rename docs/{packer/specs => specs/packer}/3. Asset Declaration and Virtual Asset Contract Specification.md (100%) rename docs/{packer/specs => specs/packer}/4. Build Artifacts and Deterministic Packing Specification.md (100%) rename docs/{packer/specs => specs/packer}/5. Diagnostics, Operations, and Studio Integration Specification.md (100%) rename docs/{packer/specs => specs/packer}/6. Versioning, Migration, and Trust Model Specification.md (100%) rename docs/{packer/specs => specs/packer}/README.md (79%) rename docs/{studio/specs => specs/studio}/1. Studio Shell and Workspace Layout Specification.md (100%) rename docs/{studio/specs => specs/studio}/2. Studio UI Foundations Specification.md (100%) rename docs/{studio/specs => specs/studio}/3. Studio Components Module Specification.md (100%) rename docs/{studio/specs => specs/studio}/4. Assets Workspace Specification.md (97%) rename docs/{studio/specs => specs/studio}/README.md (76%) delete mode 100644 docs/studio/README.md delete mode 100644 docs/studio/agendas/Palette Management in Studio Agenda.md delete mode 100644 docs/studio/agendas/README.md delete mode 100644 docs/studio/decisions/README.md delete mode 100644 docs/studio/learn/README.md delete mode 100644 docs/studio/learn/assets-workspace-execution-wave.md delete mode 100644 docs/studio/learn/bank-composition-editor.md delete mode 100644 docs/studio/learn/mental-model-asset-mutations.md delete mode 100644 docs/studio/learn/mental-model-assets-workspace.md delete mode 100644 docs/studio/learn/mental-model-studio-events-and-components.md delete mode 100644 docs/studio/learn/mental-model-studio-shell.md delete mode 100644 docs/studio/learn/pack-wizard-shell.md delete mode 100644 docs/studio/learn/project-scoped-state-and-activity.md delete mode 100644 docs/studio/pull-requests/README.md diff --git a/.discussion/index.ndjson b/.discussion/index.ndjson new file mode 100644 index 00000000..0d7bab5d --- /dev/null +++ b/.discussion/index.ndjson @@ -0,0 +1,6 @@ +{"type":"meta","next_id":{"DSC":6,"AGD":6,"DEC":3,"PLN":3,"LSN":18,"CLSN":1}} +{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} +{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} +{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} diff --git a/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md new file mode 100644 index 00000000..c5c55c3b --- /dev/null +++ b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md @@ -0,0 +1,52 @@ +--- +id: LSN-0001 +ticket: studio-docs-import +title: Assets workspace execution wave legacy lesson +created: 2026-03-26 +tags: + - studio + - legacy-import + - assets-workspace + - event-driven-ui +--- + +## Context + +Legacy import from `docs/studio/learn/assets-workspace-execution-wave.md`. + +This lesson captures the didactic consolidation of the first `Assets` workspace execution wave after the original implementation slices had already been absorbed into Studio specs and learn material. + +Relevant specs: + +- `docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md` +- `docs/studio/specs/4. Assets Workspace Specification.md` + +## Key Decisions + +### Assets workspace should remain asset-first, event-driven, and preview-first + +**What:** The stable workspace model treats `Assets` as a real asset workspace, separates navigator projection from details rendering, routes routine UI ownership through typed events, and keeps sensitive mutations preview-first rather than refresh-heavy or modal-first. +**Why:** The original execution wave produced many local slices, but the enduring lesson is the ownership model: local redraws instead of workspace-wide refresh, didactic asset detail ordering, workspace-local review with shell-level lifecycle visibility, and semantically separate mutation feedback. +**Trade-offs:** This model requires more deliberate component boundaries and event routing, but it avoids monolithic redraw logic and keeps the UI easier to reason about as the workspace grows. + +## Patterns and Algorithms + +- Treat `Assets` as a real workspace with explicit `loading`, `empty`, `error`, and `ready` states. +- Keep navigator updates and selected-asset details updates independently owned. +- Use typed workspace events for local state flow instead of defaulting to `refresh()`. +- Keep activity at shell scope, while review and mutation reasoning stay inside the workspace. +- Reserve modal confirmation for high-risk commit boundaries; use inline preview as the default review surface. + +## Pitfalls + +- Treating `Assets` like a filesystem explorer with extra badges. +- Rebuilding navigator, details, and unrelated controls for row-scoped changes. +- Letting details sections depend on one monolithic selected-asset redraw. +- Using logs as the main explanation surface for mutations. +- Publishing shell activity without keeping workspace-local review visible. + +## Takeaways + +- The durable lesson from the first `Assets` execution wave is the ownership model, not the historical sequencing of implementation slices. +- Event-directed local redraw and preview-first mutation review are foundational Studio patterns for the asset workspace. +- Legacy source attribution: `docs/studio/learn/assets-workspace-execution-wave.md`. diff --git a/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md new file mode 100644 index 00000000..b6d011bc --- /dev/null +++ b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md @@ -0,0 +1,47 @@ +--- +id: LSN-0002 +ticket: studio-docs-import +title: Bank composition editor legacy lesson +created: 2026-03-26 +tags: + - studio + - legacy-import + - bank-composition + - staged-editing +--- + +## Context + +Legacy import from `docs/studio/learn/bank-composition-editor.md`. + +This lesson captures the first-wave `Bank Composition` model as a didactic Studio pattern inside `Asset Details`, with direct relevance to `docs/studio/specs/4. Assets Workspace Specification.md` and packer-facing integration boundaries. + +## Key Decisions + +### Bank composition should use a Studio DTO boundary and staged session coordinator + +**What:** `Bank Composition` should operate through Studio-owned DTOs, intentionally dumb visual components, one section-scoped coordinator built around `StudioFormSession`, minimal public workspace-bus notifications, and a persistence path that goes through packer rather than direct Studio writes. +**Why:** Direct binding to raw packer/runtime shapes, rule-heavy generic controls, and direct `asset.json` writes would collapse family-specific rules into the wrong layer and duplicate authority that belongs to packer. +**Trade-offs:** The section needs a dedicated coordinator and DTO projection layer, but that cost keeps component boundaries honest and makes family-specific capacity and transfer semantics easier to control. + +## Patterns and Algorithms + +- Keep `available` and `selected` state in Studio-owned DTOs rather than raw packer objects. +- Land the section shell early and follow the existing staged-edit rhythm: `change`, `apply`, `reset`, `cancel`. +- Keep `StudioDualListView` and `StudioAssetCapacityMeter` state-driven rather than rule-driven. +- Let the section-scoped coordinator own draft lifecycle, transfer/reorder effects, blockers, hints, and apply handling. +- Submit ordered selected files to packer, then rebind from refreshed persisted state after apply. + +## Pitfalls + +- Binding the section UI directly to raw snapshot rows or manifest shape. +- Hiding bank-family rules inside the dual list or capacity meter. +- Creating a second staged-edit model parallel to `StudioFormSession`. +- Turning every local action into a public workspace-bus event. +- Writing `asset.json` directly from Studio. + +## Takeaways + +- The lasting lesson is not the specific first-wave editor controls; it is the ownership boundary between projection, orchestration, dumb components, and packer persistence. +- Section-scoped coordinators are the right place for family-specific editing semantics in Studio. +- Legacy source attribution: `docs/studio/learn/bank-composition-editor.md`. diff --git a/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md new file mode 100644 index 00000000..e7dd0590 --- /dev/null +++ b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md @@ -0,0 +1,47 @@ +--- +id: LSN-0003 +ticket: studio-docs-import +title: Asset mutations legacy lesson +created: 2026-03-26 +tags: + - studio + - legacy-import + - asset-mutations + - preview-first +--- + +## Context + +Legacy import from `docs/studio/learn/mental-model-asset-mutations.md`. + +This lesson preserves the didactic rule for how Studio must present asset mutations in the `Assets` workspace, aligned with `docs/studio/specs/4. Assets Workspace Specification.md` and packer integration boundaries. + +## Key Decisions + +### Sensitive asset mutations must be preview-first + +**What:** Studio should treat destructive or relocational asset mutations as preview-first workflows, keep registry impact and workspace impact distinct, and reserve modal confirmation for high-risk final commits rather than using modals as a substitute for review. +**Why:** Users lose trust quickly when the UI hides whether a mutation affects only registry state or also the physical workspace. Inline staged review keeps the user anchored in the selected asset and its consequences. +**Trade-offs:** Inline review takes more UI structure than a modal-only flow, but it produces a clearer and safer operational model for both single-asset and batch mutations. + +## Patterns and Algorithms + +- Show affected assets, scope of impact, creations/moves/deletions, blockers, warnings, and safe fixes before apply. +- Use an inline staged panel as the default review surface. +- Keep `blockers`, `warnings`, and `safe fixes` visually and semantically distinct. +- For batch operations, show an aggregate summary first and drill-down detail second. +- Reflect lifecycle milestones such as `preview ready`, `action applied`, and `action failed` at shell scope while keeping review inside the workspace. + +## Pitfalls + +- Destructive apply without preview. +- Using raw logs as the main explanation surface. +- Mixing safe fixes with deletes as if they were the same class of action. +- Showing technical diff data without user-facing interpretation. +- Forcing modal-only review for ordinary mutation flows. + +## Takeaways + +- Preview is the review; modal confirmation is only the final safety gate for high-risk commits. +- Registry impact and workspace impact must never blur in Studio mutation UX. +- Legacy source attribution: `docs/studio/learn/mental-model-asset-mutations.md`. diff --git a/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md new file mode 100644 index 00000000..76da795d --- /dev/null +++ b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md @@ -0,0 +1,51 @@ +--- +id: LSN-0004 +ticket: studio-docs-import +title: Assets workspace mental model legacy lesson +created: 2026-03-26 +tags: + - studio + - legacy-import + - assets-workspace + - asset-first +--- + +## Context + +Legacy import from `docs/studio/learn/mental-model-assets-workspace.md`. + +This lesson keeps the didactic framing for the `Assets` workspace as an asset-first, path-aware Studio surface over the packer model. + +Relevant specs: + +- `docs/studio/specs/4. Assets Workspace Specification.md` +- `docs/packer/learn/mental-model-packer.md` + +## Key Decisions + +### The assets workspace exists to teach the asset model, not to act as a nicer file browser + +**What:** The `Assets` workspace should treat asset identity as primary, path as supporting context, and the selected-asset view as a didactic explanation surface ordered around what the asset is, what it produces, what it contains, what is wrong, and what actions are available. +**Why:** A raw file-tree framing teaches the wrong mental model for packer-backed assets. The Studio needs to make managed assets, runtime-facing output, previewable inputs, and operational state understandable from the UI itself. +**Trade-offs:** Asset-first navigation requires custom navigator semantics and stronger didactic structure, but it produces a clearer and more accurate Studio view over the project. + +## Patterns and Algorithms + +- Use a custom asset navigator rather than a generic file explorer. +- Keep grouping/path visible as supporting context while preserving asset identity as primary. +- Present the selected asset in a fixed teaching order: `Summary`, `Runtime Contract`, `Inputs / Preview`, `Diagnostics`, `Actions`. +- Treat preview as part of the bridge between the conceptual asset model and real project materials. + +## Pitfalls + +- Turning the workspace into a filesystem explorer with badges. +- Making path the true identity instead of the asset. +- Showing only diagnostics and forgetting the asset model itself. +- Treating orphan as equivalent to broken. +- Hiding runtime-facing information behind technical dumps. + +## Takeaways + +- The key durable rule is `asset-first`, not `file-first`. +- Path-awareness is supporting context, not the primary identity model. +- Legacy source attribution: `docs/studio/learn/mental-model-assets-workspace.md`. diff --git a/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md new file mode 100644 index 00000000..bf6891d9 --- /dev/null +++ b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md @@ -0,0 +1,45 @@ +--- +id: LSN-0005 +ticket: studio-docs-import +title: Studio events and components legacy lesson +created: 2026-03-26 +tags: + - studio + - legacy-import + - events + - components +--- + +## Context + +Legacy import from `docs/studio/learn/mental-model-studio-events-and-components.md`. + +This lesson preserves the Studio-wide mental model for typed events and the `prometeu-studio-components` control layer. + +## Key Decisions + +### Studio should grow through typed events and a Studio-owned control layer + +**What:** The Studio should use a typed event model with both workspace buses and a global bus, automatically republishing workspace events upward, while visible controls should come through `prometeu-studio-components` rather than raw JavaFX usage scattered across the app. +**Why:** Direct references between shell, workspaces, and services create coupling that becomes hard to unwind as the application gains global activity, background operations, multiple workspaces, and cross-cutting actions. Raw JavaFX use also causes naming, styling, and behavior drift. +**Trade-offs:** This approach adds explicit control layers and event publication paths, but it keeps the UI dialect smaller, more opinionated, and easier to evolve consistently. + +## Patterns and Algorithms + +- Give each workspace its own bus and republish workspace events to the global Studio bus. +- Keep event publication explicit and typed. +- Use `prometeu-studio-components` as the Studio-facing control API rather than reimplementing JavaFX wholesale. +- When adding UI code, ask whether the behavior is an event and whether the control is part of the Studio-visible dialect. + +## Pitfalls + +- Letting shell, workspaces, and services call each other directly by convenience. +- Spreading raw JavaFX controls directly across the app. +- Recreating local wrappers and styling hooks inconsistently. +- Treating the component layer as a full JavaFX replacement instead of a focused Studio API. + +## Takeaways + +- Typed events and a Studio-owned control layer solve different problems, but together they prevent architectural drift as the UI grows. +- Workspace-local segregation and global shell visibility both matter; one bus alone is not enough. +- Legacy source attribution: `docs/studio/learn/mental-model-studio-events-and-components.md`. diff --git a/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md new file mode 100644 index 00000000..bcd31b4c --- /dev/null +++ b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md @@ -0,0 +1,49 @@ +--- +id: LSN-0006 +ticket: studio-docs-import +title: Studio shell mental model legacy lesson +created: 2026-03-26 +tags: + - studio + - legacy-import + - shell + - workspace-boundary +--- + +## Context + +Legacy import from `docs/studio/learn/mental-model-studio-shell.md`. + +This lesson preserves the Studio-wide boundary between shell framing concerns and workspace operational detail. + +Relevant spec: + +- `docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md` + +## Key Decisions + +### The shell should frame workspaces without absorbing their operational detail + +**What:** The Studio shell owns project entry, global menus, fixed workspace navigation, the workspace host, right-side utility surface, and always-visible run control, while each workspace owns its own main body and domain-specific operational detail. +**Why:** Early JavaFX apps often collapse into one giant frame where every new concern lands at shell scope. The chosen shell model avoids that drift and keeps topology stable without prematurely committing to a fully docked IDE model. +**Trade-offs:** A structured shell limits early flexibility compared with full docking, but it prevents the codebase from solving layout-persistence and docking complexity before the product actually needs it. + +## Patterns and Algorithms + +- Keep shell concerns focused on framing, not workspace internals. +- Keep operational detail such as asset-management views, debugger/profiler content, and workspace-local logs inside the relevant workspace. +- Treat `Run` as a persistent shell control because it is a primary action rather than a secondary panel. +- Use the practical rule: framing concerns go to the shell; workspace operational detail stays in the workspace. + +## Pitfalls + +- Adding every new concern to one giant shell layout. +- Treating shell-wide console surfaces as mandatory for all detailed logs. +- Introducing docking complexity before the product topology is proven. +- Hiding primary actions like `Run` behind avoidable navigation friction. + +## Takeaways + +- The shell frames workspaces; it does not absorb them. +- The shell/workspace boundary is a product rule, not just a layout preference. +- Legacy source attribution: `docs/studio/learn/mental-model-studio-shell.md`. diff --git a/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md new file mode 100644 index 00000000..487ee69e --- /dev/null +++ b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md @@ -0,0 +1,47 @@ +--- +id: LSN-0007 +ticket: studio-docs-import +title: Pack wizard shell legacy lesson +created: 2026-03-26 +tags: + - studio + - legacy-import + - pack-wizard + - packer-boundary +--- + +## Context + +Legacy import from `docs/studio/learn/pack-wizard-shell.md`. + +This lesson keeps the first-wave Studio rule for the `Pack` wizard as a shell over packer-owned operations, aligned with `docs/studio/specs/4. Assets Workspace Specification.md` and packer integration docs. + +## Key Decisions + +### Pack should be a Studio-owned wizard shell over packer-owned operations + +**What:** The `Pack` flow should be a phase-based wizard with `Summary`, `Validation`, `Packing`, and `Result`, where Studio owns presentation and state binding while packer owns build-set summary, validation, execution, progress, and result semantics. +**Why:** A plausible-looking Studio modal can quietly reimplement packer semantics or hide operational phases. The wizard should expose those phases without pretending Studio owns build execution. +**Trade-offs:** The wizard structure is more explicit than one opaque modal state, but it keeps operational ownership honest and makes blocked, failed, and successful outcomes easier to reason about. + +## Patterns and Algorithms + +- Treat `Pack` as a workspace-level action over the current build set, not a selected-asset action. +- Ask packer for the build-set summary instead of recomputing it locally from navigator state. +- Use a separate validation phase that runs only on `registered + included in build`. +- Reflect packer-owned progress honestly and keep the first wave non-cancelable if packer does not support cancel. +- Make `assets.pa` the primary runtime artifact in the result summary; companion artifacts remain supporting detail. + +## Pitfalls + +- Treating pack summary as a local Studio recomputation. +- Using one opaque modal state instead of explicit operational phases. +- Letting unrelated assets influence wizard validation. +- Exposing fake cancel behavior unsupported by packer. +- Making companion artifacts dominate the main result summary. + +## Takeaways + +- The important lasting rule is ownership: Studio shells the flow, packer owns the semantics. +- Explicit phases are a didactic and operational feature, not decorative UI ceremony. +- Legacy source attribution: `docs/studio/learn/pack-wizard-shell.md`. diff --git a/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md new file mode 100644 index 00000000..17948143 --- /dev/null +++ b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md @@ -0,0 +1,50 @@ +--- +id: LSN-0008 +ticket: studio-docs-import +title: Project-scoped state and activity legacy lesson +created: 2026-03-26 +tags: + - studio + - legacy-import + - project-state + - activity +--- + +## Context + +Legacy import from `docs/studio/learn/project-scoped-state-and-activity.md`. + +This lesson preserves the rule for project-local Studio state and shell activity persistence. + +Relevant spec: + +- `docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md` + +## Key Decisions + +### Project-local Studio state should live under `.studio/` inside the project root + +**What:** Project-local Studio state should be rooted at `.studio/`, shell activity should be persisted and restored per project, persisted history should be bounded, and `.studio/` should remain the reserved root for future project-local Studio settings. +**Why:** If project-local state is stored as if it were application-global, the shell mixes unrelated histories and stops teaching what happened in the currently opened project. +**Trade-offs:** This design requires project-scoped persistence logic and bounded retention, but it preserves causality and keeps Studio-owned project data in one obvious root. + +## Patterns and Algorithms + +- Create `.studio/` during new-project scaffolding. +- Load shell activity when the project opens. +- Append new activity to the current project's local history. +- Trim persisted activity to the latest `500` entries. +- Keep launcher-global concerns outside the project-local `.studio/` root. + +## Pitfalls + +- Treating project activity as launcher-global state. +- Mixing multiple projects into one persisted activity history. +- Leaving project-local Studio files in ad hoc roots instead of `.studio/`. +- Allowing activity persistence to grow without a hard cap. + +## Takeaways + +- Project-local history must preserve causality for the currently opened project. +- `.studio/` is the reserved home for project-scoped Studio state. +- Legacy source attribution: `docs/studio/learn/project-scoped-state-and-activity.md`. diff --git a/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md new file mode 100644 index 00000000..6bd62e41 --- /dev/null +++ b/.discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md @@ -0,0 +1,51 @@ +--- +id: LSN-0016 +ticket: studio-docs-import +title: Studio docs import pattern +created: 2026-03-26 +tags: + - studio + - migration + - discussion-framework + - import-pattern +--- + +## Context + +This lesson summarizes the completed migration of `docs/studio` into `.discussion/`. + +The original migration control artifacts were: + +- `AGD-0001` +- `DEC-0001` +- `PLN-0001` + +Those workflow files are being deleted during housekeeping. The index remains the permanent historical record. + +## Key Decisions + +### Domain documentation import should preserve retained truth instead of reconstructing deleted history + +**What:** The `docs/studio` migration imported only retained artifacts, rewrote them into framework-native templates, turned retained `learn` documents into legacy lessons, kept `specs` outside `.discussion/`, and promoted imported open agendas into their own new discussions. +**Why:** Reconstructing deleted decisions or plans would fabricate workflow history. The retained source set already contained the truth that mattered: one open agenda, zero retained decisions, zero retained plans, and a didactic learn corpus. +**Trade-offs:** This approach requires explicit editorial normalization and separate migration bookkeeping, but it yields a canonical framework surface without inventing missing history. + +## Patterns and Algorithms + +- Import only currently retained domain artifacts. +- Rewrite imported material into native framework templates. +- Turn retained `learn` material into legacy lessons under the migration discussion directory. +- Split retained open agendas into new discussions rather than leaving them nested inside the migration discussion. +- Keep `specs` as external normative references. +- Use housekeeping to delete completed migration control artifacts after their durable lesson is recorded. + +## Pitfalls + +- Recreating deleted decisions or plans from README summaries. +- Treating imported legacy lessons as if they came from framework-native execution rather than backfill. +- Leaving completed migration control artifacts in place after the durable pattern is already preserved. + +## Takeaways + +- The migration pattern is now reusable for other domains: retained agendas become new discussions, retained learn becomes legacy lessons, and completed migration control artifacts are disposable after housekeeping. +- Legacy source attribution for imported content remains in the imported lessons themselves; this lesson captures the migration pattern rather than one domain-specific document. diff --git a/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md new file mode 100644 index 00000000..0f1cf3b8 --- /dev/null +++ b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md @@ -0,0 +1,44 @@ +--- +id: LSN-0009 +ticket: packer-docs-import +title: Packer mental model legacy lesson +created: 2026-03-26 +tags: + - packer + - legacy-import + - mental-model +--- + +## Context + +Legacy import from `docs/packer/learn/mental-model-packer.md`. + +This lesson preserves the high-level didactic framing of what the packer is and is not. + +## Key Decisions + +### The packer turns asset workspaces into stable asset artifacts + +**What:** The packer is neither cartridge shipper, runtime reader, nor generic file janitor. It is the system that turns a managed asset workspace into stable runtime-facing and tool-facing artifacts. +**Why:** Contributors drift quickly when they treat packer behavior as a mix of authoring convenience, runtime semantics, and shipping responsibilities rather than one explicit artifact-producing domain. +**Trade-offs:** This framing forces sharper boundaries between packer, runtime, shipper, and Studio, but it keeps contracts and responsibilities legible. + +## Patterns and Algorithms + +- Treat the managed asset root as the unit of management. +- Split source-of-truth responsibilities between registry state and per-asset declaration. +- Keep `asset_id` and `asset_name` as separate concepts. +- Treat `assets.pa` as the authoritative runtime-facing artifact. +- Prefer determinism, explicit declaration, and canonical serialization. + +## Pitfalls + +- Treating the packer like a generic filesystem janitor. +- Collapsing `asset_id` and `asset_name` into one concept. +- Forgetting that determinism is part of the artifact contract chain. + +## Takeaways + +- The packer owns artifact production, not runtime reading or shipping. +- Stable asset identity and deterministic output are central to the whole domain. +- Legacy source attribution: `docs/packer/learn/mental-model-packer.md`. diff --git a/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md new file mode 100644 index 00000000..8adf04d8 --- /dev/null +++ b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md @@ -0,0 +1,43 @@ +--- +id: LSN-0010 +ticket: packer-docs-import +title: Asset identity and runtime contract legacy lesson +created: 2026-03-26 +tags: + - packer + - legacy-import + - asset-identity + - runtime-contract +--- + +## Context + +Legacy import from `docs/packer/learn/mental-model-asset-identity-and-runtime-contract.md`. + +This lesson preserves the distinction between stable artifact identity and logical naming. + +## Key Decisions + +### `asset_id` and `asset_name` are intentionally different + +**What:** `asset_id` is the stable artifact identity used for runtime-facing stability and preload integrity, while `asset_name` remains a logical, human-facing, code-facing reference. +**Why:** Using only `asset_name` makes rename behave like identity breakage, while using only `asset_id` everywhere today makes source-level ergonomics worse. The architecture intentionally keeps both. +**Trade-offs:** Carrying both values increases conceptual surface area, but it avoids forcing authoring ergonomics and stable runtime identity into one compromised field. + +## Patterns and Algorithms + +- Use `asset_id` when the question is stable artifact identity. +- Use `asset_name` when the question is authoring/reference ergonomics. +- Keep both values visible in runtime-facing asset tables. + +## Pitfalls + +- Treating rename as identity change. +- Treating name-only references as stable preload/bootstrap identity. +- Forcing code-facing APIs into raw integer identity too early. + +## Takeaways + +- Stable identity and logical naming solve different problems. +- Runtime artifact correctness should prefer `asset_id`; human-facing and source-facing flows may still use `asset_name`. +- Legacy source attribution: `docs/packer/learn/mental-model-asset-identity-and-runtime-contract.md`. diff --git a/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md new file mode 100644 index 00000000..762179e0 --- /dev/null +++ b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md @@ -0,0 +1,46 @@ +--- +id: LSN-0011 +ticket: packer-docs-import +title: Foundations workspace runtime and build legacy lesson +created: 2026-03-26 +tags: + - packer + - legacy-import + - foundations + - deterministic-build +--- + +## Context + +Legacy import from `docs/packer/learn/foundations-workspace-runtime-and-build.md`. + +This lesson preserves the stable foundation for workspace control, runtime snapshots, writes, and deterministic build output. + +## Key Decisions + +### The stable foundation is filesystem-first authoring plus coherent snapshot-backed runtime and deterministic build + +**What:** The packer keeps the workspace open and filesystem-first, anchors managed identity in registry and asset declarations, serves reads through coherent runtime snapshots, coordinates writes through packer-owned lanes, and emits deterministic build outputs from validated state. +**Why:** The original implementation wave spread this knowledge across many PR slices, which stopped being a good onboarding surface. The stable model needed one didactic consolidation. +**Trade-offs:** This architecture demands stronger ownership of snapshots, write coordination, and deterministic ordering, but it prevents UI heuristics, traversal order, or cache state from silently becoming semantic authority. + +## Patterns and Algorithms + +- Keep `asset_id` stable and separate from `asset_name`. +- Treat `asset.json` as authoring intent rather than registry bookkeeping. +- Read from coherent runtime snapshots. +- Serialize commit-bearing writes through one project-scoped semantic lane. +- Order build outputs deterministically by managed identity. + +## Pitfalls + +- Treating `asset_name` as stable runtime identity. +- Moving registry-owned fields into `asset.json`. +- Depending on traversal order or UI order for build layout. +- Treating cache state as semantic authority. + +## Takeaways + +- The packer foundation is as much about ownership and determinism as it is about file formats. +- Filesystem durability, snapshot coherence, and deterministic emission must stay aligned. +- Legacy source attribution: `docs/packer/learn/foundations-workspace-runtime-and-build.md`. diff --git a/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md new file mode 100644 index 00000000..bfc38df3 --- /dev/null +++ b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md @@ -0,0 +1,45 @@ +--- +id: LSN-0012 +ticket: packer-docs-import +title: Runtime ownership and Studio boundary legacy lesson +created: 2026-03-26 +tags: + - packer + - legacy-import + - runtime-boundary + - studio-boundary +--- + +## Context + +Legacy import from `docs/packer/learn/runtime-ownership-and-studio-boundary.md`. + +This lesson preserves the ownership boundary between packer operational semantics and Studio presentation. + +## Key Decisions + +### Packer owns operational asset semantics; Studio consumes translated responses and events + +**What:** The stable boundary is filesystem-first authoring, project-scoped runtime snapshots for coherent reads, one serialized semantic write lane per project, authoritative packer events with causality, and Studio adapters that translate but do not invent semantics. +**Why:** Without this boundary, the system drifts into split-brain behavior where Studio and packer both try to own summaries, mutation meaning, or reconcile logic. +**Trade-offs:** Strong semantic ownership in packer makes Studio adapters less flexible, but it keeps lifecycle, concurrency, and event meaning testable and consistent. + +## Patterns and Algorithms + +- Keep divergence explicit packer state rather than silent repair. +- Allow coherent `read/read`, serialize `write/write`, and avoid torn `read/write` views. +- Preserve operation causality with stable ids and monotonic sequence. +- Let Studio remap data for presentation without recomputing semantics. + +## Pitfalls + +- Rebuilding packer summaries from Studio-side heuristics. +- Treating adapters as a second semantic authority. +- Hiding divergence by silent refresh. +- Allowing same-project writes to race. + +## Takeaways + +- Studio should present packer semantics, not recreate them. +- Event causality and write-lane ownership are part of the domain contract. +- Legacy source attribution: `docs/packer/learn/runtime-ownership-and-studio-boundary.md`. diff --git a/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md new file mode 100644 index 00000000..de66f95d --- /dev/null +++ b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md @@ -0,0 +1,44 @@ +--- +id: LSN-0013 +ticket: packer-docs-import +title: Metadata convergence and runtime sink legacy lesson +created: 2026-03-26 +tags: + - packer + - legacy-import + - metadata + - runtime-sink +--- + +## Context + +Legacy import from `docs/packer/learn/mental-model-metadata-convergence-and-runtime-sink.md`. + +This lesson preserves the rule that runtime-consumable metadata converges into one effective sink. + +## Key Decisions + +### Runtime-consumable metadata converges to `AssetEntry.metadata` + +**What:** Authoring contracts may segment metadata by concern, but all runtime-consumable metadata must normalize deterministically into `AssetEntry.metadata`. Payload slicing fields such as `AssetEntry.offset` and `AssetEntry.size` keep their own semantics and do not replace internal indexing values. +**Why:** Without an explicit convergence rule, runtime readers, normalization behavior, and metadata collision handling all become accidental and non-deterministic. +**Trade-offs:** Deterministic convergence requires explicit normalization rules and collision handling, but it gives runtime consumers one clear reading surface. + +## Patterns and Algorithms + +- Segment metadata in source declarations when useful for authoring ergonomics. +- Normalize all runtime-consumable metadata into one root map in emitted asset entries. +- Fail or use explicit rules on collisions rather than silently overwriting. +- Keep payload slicing and internal indexing semantics distinct. + +## Pitfalls + +- Treating segmented declaration metadata as multiple runtime sinks. +- Allowing silent key overwrite. +- Mixing asset-table slicing semantics with internal indexing offsets. + +## Takeaways + +- Runtime consumers should read runtime metadata from `AssetEntry.metadata`. +- Convergence behavior must live in specs and tests, not only in code comments. +- Legacy source attribution: `docs/packer/learn/mental-model-metadata-convergence-and-runtime-sink.md`. diff --git a/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md new file mode 100644 index 00000000..1eafb7d9 --- /dev/null +++ b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md @@ -0,0 +1,47 @@ +--- +id: LSN-0014 +ticket: packer-docs-import +title: Pack wizard summary validation and pack execution legacy lesson +created: 2026-03-26 +tags: + - packer + - legacy-import + - pack-wizard + - validation + - execution +--- + +## Context + +Legacy import from `docs/packer/learn/pack-wizard-summary-validation-and-pack-execution.md`. + +This lesson preserves the packer-owned semantics behind the Studio-side pack wizard. + +## Key Decisions + +### Summary, validation, and pack execution are distinct packer-owned phases + +**What:** `summary` is a fast snapshot-backed preflight view, `validation` is a blocking-diagnostics gate over the same active pack set, and `packWorkspace(...)` is the only artifact-emitting operation, rerunning the gate on a fresh frozen snapshot and promoting staged outputs only after coherent success. +**Why:** Studio-side shelling only works if packer provides one coherent operational story instead of a mix of stale UI assumptions and live filesystem rereads. +**Trade-offs:** This model is stricter and less forgiving than trusting previous UI state, but it prevents stale or torn assumptions from leaking into final build output. + +## Patterns and Algorithms + +- Define the active pack set as `registered + included in build`. +- Keep summary fast and snapshot-backed. +- Let only blocking diagnostics fail first-wave validation. +- Re-run the gate on a fresh execution snapshot before emission. +- Stage outputs before promoting them to final `build/`. + +## Pitfalls + +- Treating summary as emitted-artifact preview. +- Validating a broader set than the active pack set. +- Letting warnings fail the first-wave gate. +- Reading live filesystem bytes after frozen execution starts. + +## Takeaways + +- Green validation from a few seconds earlier is not enough; pack execution must revalidate on a fresh frozen snapshot. +- Packer-owned result semantics should be enough for Studio to render packing and result phases. +- Legacy source attribution: `docs/packer/learn/pack-wizard-summary-validation-and-pack-execution.md`. diff --git a/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md new file mode 100644 index 00000000..6d37d17e --- /dev/null +++ b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md @@ -0,0 +1,46 @@ +--- +id: LSN-0015 +ticket: packer-docs-import +title: Tile bank packing contract legacy lesson +created: 2026-03-26 +tags: + - packer + - legacy-import + - tile-bank + - packing-contract +--- + +## Context + +Legacy import from `docs/packer/learn/tile-bank-packing-contract.md`. + +This lesson preserves the first-wave producer contract for tile-bank assets. + +## Key Decisions + +### Tile bank packing emits one canonical payload per asset with explicit normalization and early structural validation + +**What:** The first-wave contract emits one canonical `TILES/indexed_v1` payload per asset, normalizes artifacts by explicit `artifacts[*].index`, packs one fixed `256 x 256` row-major sheet with packed `u4` pixels and `RGB565` palette blocks, treats palette identity as semantic rather than positional, and surfaces structural blockers early in walker/materialization. +**Why:** The repository needed one explicit producer contract for tile banks rather than a mix of implicit artifact ordering, late byte-emission surprises, and unstable palette identity. +**Trade-offs:** This contract is more explicit and restrictive than ad hoc per-artifact packing, but it yields stable reviewability, predictable runtime metadata, and earlier validation. + +## Patterns and Algorithms + +- Treat `1 artifact = 1 tile`. +- Normalize artifact identity by ascending declared `index`. +- Emit one canonical bank raster rather than concatenated artifact-local binaries. +- Keep palette identity explicit with `{ index, palette }`. +- Produce structural diagnostics before late pack-only phases. + +## Pitfalls + +- Treating artifact declaration order as semantic tile identity. +- Embedding per-tile palette choice in packed payload. +- Flattening all metadata into one ambiguous map. +- Discovering tile-bank blockers only during final byte emission. + +## Takeaways + +- The tile-bank producer contract depends on canonical normalization and early structural validation. +- Palette identity should be semantic and explicit, not positional by list order. +- Legacy source attribution: `docs/packer/learn/tile-bank-packing-contract.md`. diff --git a/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md new file mode 100644 index 00000000..88dfd8bd --- /dev/null +++ b/.discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md @@ -0,0 +1,50 @@ +--- +id: LSN-0017 +ticket: packer-docs-import +title: Packer docs import pattern +created: 2026-03-26 +tags: + - packer + - migration + - discussion-framework + - import-pattern +--- + +## Context + +This lesson summarizes the completed migration of `docs/packer` into `.discussion/`. + +The original migration control artifacts were: + +- `AGD-0003` +- `DEC-0002` +- `PLN-0002` + +Those workflow files are being deleted during housekeeping. The index remains the permanent historical record. + +## Key Decisions + +### Packer domain import follows the same retained-set migration pattern as Studio + +**What:** The `docs/packer` migration imported only retained artifacts, promoted retained open agendas into new discussions, preserved the empty retained sets for decisions and plans, rewrote retained `learn` into legacy lessons, and kept `specs` outside `.discussion/`. +**Why:** The packer domain already had two live agendas and a didactic learn corpus, but no retained decisions or plans. The migration needed to preserve that real operational state instead of fabricating symmetry. +**Trade-offs:** The pattern keeps workflow truth honest, but it requires explicit editorial rewriting and separate migration bookkeeping before the resulting discussions can continue normally. + +## Patterns and Algorithms + +- Treat README-declared empty retained sets as authoritative. +- Create one new discussion per retained agenda. +- Backfill retained learn documents as legacy lessons in the migration discussion directory. +- Keep normative specs external to the workflow control plane. +- Delete completed migration control artifacts after recording the durable pattern lesson. + +## Pitfalls + +- Manufacturing missing decisions or plans to make the imported tree look symmetric. +- Forgetting to separate imported open agendas into their own discussions. +- Keeping completed migration scaffolding around after the lesson already captures the reusable pattern. + +## Takeaways + +- Domain migration is a repeatable workflow: preserve retained truth, normalize into framework templates, split open agendas into real discussions, and delete completed migration scaffolding after housekeeping. +- This lesson captures the migration pattern; the imported packer legacy lessons capture the domain knowledge itself. diff --git a/.discussion/workflow/agendas/AGD-0002-palette-management-in-studio.md b/.discussion/workflow/agendas/AGD-0002-palette-management-in-studio.md new file mode 100644 index 00000000..17f8a801 --- /dev/null +++ b/.discussion/workflow/agendas/AGD-0002-palette-management-in-studio.md @@ -0,0 +1,116 @@ +--- +id: AGD-0002 +ticket: palette-management-in-studio +title: Palette Management in Studio +status: open +created: 2026-03-26 +resolved: +decision: +tags: + - studio + - legacy-import + - palette-management + - tile-bank + - packer-boundary +--- + +## Pain + +Studio already has a retained agenda for palette management in the `tile bank` form session, but that agenda exists only under `docs/studio/agendas/` and therefore sits outside the discussion-framework lifecycle. + +Without importing it into `.discussion/`, the canonical discussion surface would lose the still-open Studio question about: + +- how candidate palettes are presented; +- how `1..64` palette capacity is enforced and explained; +- how preview and selection behave inside the asset workflow; +- how Studio UX stays separate from packer-owned extraction, validation, identity, and persistence. + +## Context + +Legacy source: `docs/studio/agendas/Palette Management in Studio Agenda.md` + +Domain owner: `docs/studio` +Cross-domain impact: `docs/packer` + +The retained agenda is intentionally scoped to `tile bank`. + +The imported context keeps the same baseline: + +- every `*.png` input of a tile bank is one tile; +- each tile yields one extracted palette during cache construction; +- developers may also work with favorite palettes and asset palettes; +- each bank may integrate at most `64` palettes; +- each palette contains `16` colors with a default color-key baseline; +- Studio owns curation UX, while packer remains authoritative for extraction, identity, validation, and persistence. + +The current UI shape already converged on: + +- a left-side transfer list for candidate and selected palettes; +- custom palette rendering with swatches and source indicators; +- a right-side preview panel with tile/file selector, tile preview, and applied palette strip. + +## Open Questions + +- [ ] How should Studio detect and present duplicate or near-equivalent palettes across tile-derived, favorite, and asset-level sources? +- [ ] Are favorites project-scoped references to existing palettes, or can they diverge into editable copies before bank admission? +- [ ] What is the canonical user-facing identity of a candidate palette in Studio: source bucket plus logical name, file path, extraction origin tile, stable id, or a combination? +- [ ] Should extracted tile palettes always enter the candidate set automatically, or can the developer suppress some of them before curation? +- [ ] Should clicking a palette on the `selected` side be the only interaction needed to change the previewed palette in the first wave? +- [ ] Which palette operations are read-only in the first wave, and which require staged preview/apply treatment? +- [ ] Which parts of this interaction model should remain explicitly `tile bank`-specific, and which parts are reusable Studio form-session primitives? +- [ ] Does the first release need only an asset-scoped `tile bank` section, or also a project-level palette browser for discovery and favorites management? + +## Options + +### Option A - Automatic Integration +- **Approach:** Treat extracted tile palettes as implicit inputs and integrate them automatically without explicit user curation. +- **Pro:** Lowest immediate UX cost. +- **Con:** Hides palette-budget reasoning, weakens deliberate composition, and makes source distinctions harder to understand. +- **Maintainability:** Weak. It pushes important bank rules into implicit behavior. + +### Option B - Asset-Scoped Curated Selection +- **Approach:** Treat bank palettes as an asset-scoped curated selection built from tile-derived palettes, favorites, and asset palettes, with Studio owning the curation UX and packer owning persistence. +- **Pro:** Matches the concrete `tile bank` workflow and keeps authority boundaries clear. +- **Con:** Requires explicit UX for capacity, identity, deduplication, and preview semantics. +- **Maintainability:** Strong. It makes responsibilities explicit and keeps family-specific rules close to the workflow that needs them. + +### Option C - Studio-Owned Palette Library +- **Approach:** Treat palettes as a broader Studio-owned library/workspace with direct local editing and persistence behavior. +- **Pro:** Potentially flexible for future palette-heavy features. +- **Con:** Duplicates packer ownership and risks creating a second authority for bank composition. +- **Maintainability:** Weak. It expands Studio responsibility before the persistence contract is closed. + +## Discussion + +The imported agenda keeps the original recommendation intact: palette management should be first-class for `tile bank`, but Studio must not become the persistence authority. + +That means the key open problem is not whether palettes exist. It is how Studio explains and curates them safely: + +- candidate aggregation from multiple sources; +- clear source and identity display; +- explicit `1..64` capacity feedback; +- a preview model that stays tied to the selected bank palettes; +- a boundary between `tile bank`-specific UX and reusable Studio primitives. + +The retained source already converged on a pragmatic first wave: + +- transfer-list selection on the left; +- palette-focused preview on the right; +- first selected palette as default preview; +- clicking on a selected palette changes the previewed palette; +- removing the current preview palette falls back to the first remaining selected palette. + +## Resolution + +Recommended direction: adopt **Option B**. + +The imported agenda preserves the retained Studio direction: + +1. palette management belongs to the `tile bank` asset workflow; +2. Studio aggregates candidate palettes from tile-derived extraction, favorites, and asset palettes; +3. the first wave uses a custom-rendered transfer list with an explicit `1..64` selected range; +4. the right-side preview panel stays tied to the current selected palette set; +5. packer remains authoritative for extraction, identity, validation, and persistence; +6. broader standalone palette-authoring workflows remain deferred. + +Next step suggestion: convert this imported agenda into a decision that closes the ownership boundary, candidate-source model, first-wave transfer-list UX, preview behavior, and reusable-vs-family-specific primitive boundary. diff --git a/.discussion/workflow/agendas/AGD-0004-tilemap-and-metatile-runtime-binary-layout.md b/.discussion/workflow/agendas/AGD-0004-tilemap-and-metatile-runtime-binary-layout.md new file mode 100644 index 00000000..c7ad7988 --- /dev/null +++ b/.discussion/workflow/agendas/AGD-0004-tilemap-and-metatile-runtime-binary-layout.md @@ -0,0 +1,97 @@ +--- +id: AGD-0004 +ticket: tilemap-and-metatile-runtime-binary-layout +title: Tilemap and Metatile Runtime Binary Layout +status: open +created: 2026-03-26 +resolved: +decision: +tags: + - packer + - legacy-import + - tilemap + - metatile + - runtime-layout +--- + +## Pain + +The repository has conceptual alignment around map responsibility split and active-window residency, but still lacks a closed runtime binary contract for handheld maps. + +Without a canonical decision: + +- packer cannot close the output specification for map artifacts; +- runtime lacks one stable reading baseline; +- Studio cannot align authoring and preview schemas with one binary target. + +## Context + +Legacy source: `docs/packer/agendas/Tilemap and Metatile Runtime Binary Layout Agenda.md` + +Domain owner: `docs/packer` +Cross-domain impact: + +- `docs/vm-arch` +- `docs/studio` +- `docs/compiler/pbs` + +Current discussion premises retained from source: + +- visual and collision concerns should remain separated; +- map cells should not duplicate large metadata per tile; +- only a `3x3` active window of maps should remain resident in memory; +- a `64 KiB` target budget per map bank has been discussed; +- `map bank` and `tileset bank` do not need identical size rules. + +## Open Questions + +- [ ] Is `collisionId` with `5` bits (`32` classes) sufficient for expected projects? +- [ ] Should `flag0` be reserved for fast trigger semantics or contextual visual variation? +- [ ] Which optional chunks belong in `V1`, and which should wait for a later version? +- [ ] Must `map bank` stay strictly at `64 KiB`, or should capacity be variable with explicit metadata? +- [ ] What compression policy should the packer adopt by default for the stream? + +## Options + +### Option A - `u8` cells with auxiliary tables +- **Approach:** Store only one `metatileId` per cell and derive collision/flags from side tables. +- **Pro:** Smallest RAM and I/O footprint. +- **Con:** Pushes too much semantic meaning into external lookup tables. +- **Maintainability:** Medium. + +### Option B - `u16` bit-packed cells +- **Approach:** Use `16` bits per cell, with a compact split such as `visualId`, `collisionId`, and `flag0`. +- **Pro:** Balances compactness, deterministic decoding, and enough expressivity for many handheld cases. +- **Con:** Leaves less room for inline per-cell growth than `u32`. +- **Maintainability:** Strong. + +### Option C - `u32` cells +- **Approach:** Use larger cells to keep more event/flag space inline. +- **Pro:** Highest flexibility for per-cell triggers and future expansion. +- **Con:** Doubles memory cost versus `u16` without current evidence that it is needed. +- **Maintainability:** Weak for the current budget target. + +## Discussion + +The retained source already converged toward `u16` as the best baseline. + +The suggested runtime shape is: + +- fixed map header; +- contiguous cell stream; +- optional future-proof chunks. + +The proposed `U16_PACKED_V1` split keeps visual and collision references compact while preserving predictable memory usage and straightforward streaming behavior for a handheld target. + +## Resolution + +Recommended direction: adopt **Option B** as the baseline. + +Imported retained recommendation: + +1. authorship stays JSON-oriented around compact ids; +2. build output packs deterministically into `U16_PACKED_V1`; +3. runtime active-window budget remains explicit; +4. any move to `u32` should happen only through a later versioned encoding with evidence of need. + +Next step suggestion: convert this agenda into a decision that closes `U16_PACKED_V1`, propagation to `docs/vm-arch`, Studio editing schema alignment, and implementation planning for roundtrip tests. diff --git a/.discussion/workflow/agendas/AGD-0005-variable-tile-bank-palette-serialization.md b/.discussion/workflow/agendas/AGD-0005-variable-tile-bank-palette-serialization.md new file mode 100644 index 00000000..41b763a8 --- /dev/null +++ b/.discussion/workflow/agendas/AGD-0005-variable-tile-bank-palette-serialization.md @@ -0,0 +1,87 @@ +--- +id: AGD-0005 +ticket: variable-tile-bank-palette-serialization +title: Variable Tile Bank Palette Serialization +status: open +created: 2026-03-26 +resolved: +decision: +tags: + - packer + - legacy-import + - tile-bank + - palette-serialization + - versioning +--- + +## Pain + +The current tile-bank contract serializes a fixed block of `64` palettes in v1 even when an asset authors far fewer palettes. + +That keeps decoding simple, but it wastes cartridge space and leaves the system with a deliberate mismatch between authored and serialized palette counts. + +## Context + +Legacy source: `docs/packer/agendas/Variable Tile Bank Palette Serialization Agenda.md` + +Domain owner: `docs/packer` +Cross-domain dependency: + +- runtime + +Current aligned v1 contract: + +- pixels are serialized as packed `u4`; +- palettes are serialized as `RGB565 u16`; +- `palette_count = 64`; +- payload size includes a fixed `64 * 16 * 2` palette block. + +The packer now exposes: + +- `metadata.palette_count = 64` +- `metadata.palette_authored = ` + +## Open Questions + +- [ ] Should variable palette serialization arrive as a new payload version or as an incompatible change to the current one? +- [ ] If `palette_count` becomes variable, should runtime still materialize a 64-slot resident bank, or truly shrink in-memory representation too? +- [ ] Should sparse authored palette indices remain sparse in serialization, or be canonicalized into a dense runtime block? +- [ ] Which domain owns compatibility for existing cartridges: `packer`, `runtime`, or `shipper`? + +## Options + +### Option A - Keep fixed 64-palette serialization +- **Approach:** Preserve the current fixed v1 payload with zero-filled unused palette slots. +- **Pro:** No runtime change and current specs/tests remain stable. +- **Con:** Every tile bank keeps paying the full palette cost. +- **Maintainability:** Medium. + +### Option B - Move to variable palette serialization now +- **Approach:** Serialize only authored palettes and shrink payload size immediately. +- **Pro:** Better cartridge efficiency and tighter semantics for `palette_count`. +- **Con:** Reopens a just-stabilized cross-domain runtime contract and forces compatibility decisions now. +- **Maintainability:** Medium if done carefully, risky if done incidentally. + +### Option C - Keep v1 fixed and design variable serialization for v2 +- **Approach:** Preserve v1 stability now and open a later versioned follow-up for variable palette serialization. +- **Pro:** Keeps current work stable while preserving a clean path for future optimization. +- **Con:** Known waste remains in v1. +- **Maintainability:** Strong. + +## Discussion + +The retained agenda recommendation is already clear: the waste is real, but it is not a correctness bug, and reopening the runtime-facing contract immediately would mix optimization work into a freshly stabilized path. + +That makes versioned follow-up a cleaner vehicle than incidental mutation of the current contract. + +## Resolution + +Recommended direction: adopt **Option C**. + +Imported retained recommendation: + +1. keep the current fixed 64-palette contract for v1; +2. if variable serialization is desired, design it explicitly as a versioned follow-up; +3. treat compatibility, runtime representation, and sparse-vs-dense palette identity as explicit next-wave questions rather than silent payload tweaks. + +Next step suggestion: if the team wants to remove the fixed padding, open the corresponding runtime-side discussion and close the versioning/compatibility story before planning implementation. diff --git a/docs/compiler/general/README.md b/docs/compiler/general/README.md deleted file mode 100644 index 6cce3415..00000000 --- a/docs/compiler/general/README.md +++ /dev/null @@ -1,20 +0,0 @@ -# General Documentation - -This directory contains documentation that applies to language implementations in general, not only PBS. - -## Tree - -```text -docs/general/ -└── specs/ -``` - -## Purpose - -`general/specs` is the cross-language acceptance layer. - -Use it to define: - -- shared conformance and quality-gate contracts, -- shared compatibility and verification policy, -- and backend/runtime acceptance boundaries that are language-agnostic. diff --git a/docs/compiler/pbs/agendas/README.md b/docs/compiler/pbs/agendas/README.md index 90a10016..c0bdc16d 100644 --- a/docs/compiler/pbs/agendas/README.md +++ b/docs/compiler/pbs/agendas/README.md @@ -2,22 +2,35 @@ This directory contains active PBS discussion agendas. -Closed agendas are moved to `docs/pbs/agendas/archive`. +Closed agendas are moved to `docs/compiler/pbs/agendas/archive`. ## Active Agendas -1. `18.0. Backend VM Pipeline - Orchestration Agenda.md` -2. `18.1. Backend Workshop 1 - IRBackend Input Contract.md` -3. `18.2. Backend Workshop 2 - LowerToIRVM and IRVM Contract.md` -4. `18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md` -5. `18.4. Asset References in Game Code - Names vs Compile-Time Lowering Agenda.md` -6. `18.5. Ignored Call Results in Executable Lowering Agenda.md` -7. `19. Globals, Synthetic Module Init, and FRAME_RET Agenda.md` -8. `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda.md` -9. `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda.md` -10. `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md` -11. `19.4. Globals and Lifecycle Lowering to IRBackend-IRVM Agenda.md` -12. `19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda.md` +1. `18.4. Asset References in Game Code - Names vs Compile-Time Lowering Agenda.md` +2. `18.5. Ignored Call Results in Executable Lowering Agenda.md` +3. `19. Globals, Synthetic Module Init, and FRAME_RET Agenda.md` +4. `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda.md` +5. `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda.md` +6. `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md` +7. `19.4. Globals and Lifecycle Lowering to IRBackend-IRVM Agenda.md` +8. `19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda.md` + +## Consolidated Agenda 18 Material + +Agenda 18 backend-orchestration material (`18.0` through `18.3`) is no longer part of the active agenda set. + +That slice has already been propagated into: + +1. the backend execution plan in `docs/compiler/pbs/pull-requests/INDEX.md` under `Backend VM Pipeline PR Sequence (Agenda 18)`, +2. decision material such as `docs/compiler/pbs/decisions/IRVM Optimization Stage Placement Decision.md`, +3. normative backend specs: + - `docs/compiler/general/specs/19. Verification and Safety Checks Specification.md`, + - `docs/compiler/general/specs/20. IRBackend to IRVM Lowering Specification.md`, + - `docs/compiler/general/specs/21. IRVM Optimization Pipeline Specification.md`, + - `docs/compiler/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`, +4. and implemented/tested backend pipeline stages in `prometeu-compiler/prometeu-build-pipeline`. + +Only `18.4` and `18.5` remain open from the `18.*` family. ## Purpose @@ -30,7 +43,7 @@ Use an agenda when: - the scope and non-goals need to be made explicit, - the order of discussion matters. -Move an agenda to `docs/pbs/agendas/archive` once the topic is no longer active. +Move an agenda to `docs/compiler/pbs/agendas/archive` once the topic is no longer active. ## Expected Format diff --git a/docs/packer/README.md b/docs/packer/README.md deleted file mode 100644 index 7b140498..00000000 --- a/docs/packer/README.md +++ /dev/null @@ -1,112 +0,0 @@ -# Packer Documentation - -This directory contains the working, planning, normative, and didactic documentation for the `packer` domain. - -`packer` is a standalone domain. It follows the same documentary cycle used elsewhere in the repository: - -`agendas -> decisions -> pull-requests -> specs -> learn` - -## Tree - -```text -docs/packer/ -├── agendas/ -├── decisions/ -├── learn/ -├── pull-requests/ -├── specs/ -└── README.md -``` - -## Responsibilities - -### `agendas/` - -`agendas/` is a transient staging area for open packer topics. - -Use it to: - -- frame unresolved problems, -- compare options and tradeoffs, -- define scope and non-goals, -- drive discussions toward a decision. - -An agenda is a discussion artifact, not a final contract. -When a topic is fully propagated into specs and learn, the corresponding agenda should leave the retained set. - -### `decisions/` - -`decisions/` is a transient staging area for closed packer decisions before full consolidation. - -Use it to: - -- record the chosen direction, -- capture constraints and invariants, -- state what remains intentionally out of scope, -- identify which specs, plans, or code paths must be updated. - -Decisions close debate. They are not brainstorming notes. -Once their content is fully absorbed into specs and learn, they should not be retained just as historical residue. - -### `pull-requests/` - -`pull-requests/` contains self-contained execution proposals. - -Use it to: - -- package a change for review, -- plan propagation across specs and implementation, -- define acceptance criteria, -- make tests and risks explicit before editing code or final specs. - -### `specs/` - -`specs/` contains the normative packer corpus. - -Use it to: - -- consolidate the official packer contract, -- split large draft material into stable chaptered specs, -- define behavior, constraints, interfaces, and conformance expectations. - -Specs should only absorb already-closed decisions. - -### `learn/` - -`learn/` contains didactic consolidation. - -Use it to: - -- explain why the packer works the way it does, -- preserve hard-won operational knowledge, -- teach future contributors the model, pitfalls, and expected workflows, -- reorganize accumulated knowledge into a cleaner learning surface. - -`learn/` is not an archive of old decisions. - -## Recommended Flow - -The preferred packer documentation flow is: - -1. `agendas/`: open and shape the unresolved topic. -2. `decisions/`: close the architectural choice. -3. `pull-requests/`: plan how the decision will be propagated. -4. `specs/`: integrate the decision into normative text. -5. `learn/`: consolidate the final knowledge in a didactic form. - -## Practical Rule - -- `agendas/` stores currently open questions only. -- `decisions/` stores only decisions that still need propagation. -- `pull-requests/` stores only execution plans for pending work. -- `specs/` stores the normative packer contract. -- `learn/` stores teaching-oriented consolidation. - -The current packer core has already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/). -At this moment: - -- `agendas/` retains only topics that are still open; -- `decisions/` is empty because the last accepted wave was fully propagated; -- `pull-requests/` is empty because the historical execution wave was absorbed into `learn/`. - -If implementation exposes a missing architectural choice, stop and return to `agendas/` or `decisions/`. diff --git a/docs/packer/agendas/README.md b/docs/packer/agendas/README.md deleted file mode 100644 index 395acdf5..00000000 --- a/docs/packer/agendas/README.md +++ /dev/null @@ -1,54 +0,0 @@ -# Packer Agendas - -This directory contains active packer discussion agendas. - -## Active Agendas - -1. [`Tilemap and Metatile Runtime Binary Layout Agenda.md`](./Tilemap%20and%20Metatile%20Runtime%20Binary%20Layout%20Agenda.md) -2. [`Variable Tile Bank Palette Serialization Agenda.md`](./Variable%20Tile%20Bank%20Palette%20Serialization%20Agenda.md) - -Closed packer agenda waves must be absorbed into [`../specs/`](../specs/) and [`../learn/`](../learn/) instead of remaining here as historical residue. - -## Purpose - -An agenda exists to drive a decision. - -Use an agenda when: - -- the packer topic is still open, -- multiple options or tradeoffs must be evaluated, -- scope and non-goals need to be made explicit, -- the order of discussion matters, -- the team still needs a recommendation before committing direction. - -An agenda should help the reader converge, not just accumulate notes. - -## Expected Format - -A packer agenda should usually include: - -1. Title -2. Status -3. Purpose -4. Context -5. Options -6. Tradeoffs -7. Recommendation -8. Open Questions -9. Expected Follow-up - -## Writing Rules - -- Keep the document centered on unresolved questions. -- State the concrete decision the discussion is trying to produce. -- Prefer explicit tradeoffs over vague option lists. -- Avoid drafting large blocks of final normative spec text here. -- Be specific about packer scope: asset workspace, build artifacts, diagnostics, registry, shipper boundary, and related contracts. - -## Exit Rule - -An agenda should leave the active set when: - -- the main tradeoffs are understood, -- a recommendation is clear enough to adopt, -- and the topic is ready to become a decision record. diff --git a/docs/packer/agendas/Tilemap and Metatile Runtime Binary Layout Agenda.md b/docs/packer/agendas/Tilemap and Metatile Runtime Binary Layout Agenda.md deleted file mode 100644 index 47d39bed..00000000 --- a/docs/packer/agendas/Tilemap and Metatile Runtime Binary Layout Agenda.md +++ /dev/null @@ -1,152 +0,0 @@ -# Tilemap and Metatile Runtime Binary Layout Agenda - -## Status - -Open - -## Purpose - -Convergir a discussão sobre o contrato de mapa para handheld em duas camadas: - -- formato de autoria/edição (JSON legível), -- formato de execução (layout binário compacto em runtime). - -O objetivo é fechar qual estrutura será adotada para `tilemap bank`, `tileset bank` e dados de colisão/flags, com foco em previsibilidade de memória e streaming de mapas. - -## Domain Owner - -`docs/packer` - -Este tema é owner de packer porque envolve transformação de artefatos (`JSON -> BIN`), contrato de build e layout de saída para consumo do runtime. - -Domínios impactados (cross-domain): - -- `docs/vm-arch` (contrato de leitura em runtime e limites de memória), -- `docs/studio` (edição/preview de mapas no workspace), -- `docs/compiler/pbs` (integração futura com referências de assets em código, quando aplicável). - -## Problem - -Hoje existe alinhamento conceitual de que: - -1. visual e colisão devem ser separados por responsabilidade; -2. o mapa não deve repetir metadados extensos por célula; -3. apenas uma janela ativa de até `9` mapas deve ficar residente em memória. - -Mas ainda não existe decisão formal sobre: - -- layout binário final por célula em runtime, -- orçamento por mapa e por janela ativa, -- responsabilidade exata entre `map bank` e `tileset bank`. - -Sem esse contrato, o packer não fecha especificação de saída e o runtime/studio ficam sem baseline único. - -## Context - -Premissas atuais da discussão: - -- `tileset bank` pode ter tamanho diferente dos demais banks; -- `map bank` não precisa seguir o mesmo tamanho de `tileset bank`; -- mapa deve referenciar IDs compactos (visual, colisão e flags), em vez de duplicar estrutura completa por célula; -- paletas por bank continuam sendo opção válida para preservar decisões artísticas locais; -- orçamento alvo foi discutido no contexto de `64 KiB` por map bank e janela ativa de `3x3` mapas (`9` residentes). - -## Options - -### Option A — Célula `u8` (mapa ultra-compacto) - -- Cada célula armazena apenas `metatileId` (`0..255`). -- Colisão/flags vêm de tabela auxiliar por `metatileId`. - -### Option B — Célula `u16` bit-packed (recomendação inicial) - -- Cada célula usa `16 bits` com divisão sugerida: - - `visualId`: `10 bits` (`0..1023`), - - `collisionId`: `5 bits` (`0..31`), - - `flags`: `1 bit` (`0..1`) ou reservado para evolução. -- Permite desacoplamento visual/lógico sem custo de `u32`. - -### Option C — Célula `u32` (maior flexibilidade) - -- Exemplo de divisão: - - `visualId`: `12 bits`, - - `collisionId`: `8 bits`, - - `flags/event`: `12 bits`. -- Ganho de expressividade para triggers/eventos inline; custo de memória dobra vs `u16`. - -## Tradeoffs - -- Option A minimiza RAM e I/O, mas limita variedade visual e desloca muita semântica para tabelas externas. -- Option B oferece bom equilíbrio para handheld: compacta, previsível e com espaço suficiente para muitos casos de mapa. -- Option C simplifica evolução funcional (eventos por célula), mas pressiona memória e banda de streaming sem necessidade comprovada agora. - -## Runtime Binary Structure (focus) - -Estrutura sugerida para runtime (baseada em Option B): - -1. **Map Header (fixo)** - - `magic` (`4 bytes`) - - `version` (`u16`) - - `width` (`u16`) - - `height` (`u16`) - - `cellEncoding` (`u8`) — ex.: `1 = U16_PACKED_V1` - - `visualBankId` (`u16`) - - `collisionBankId` (`u16`) - - `reserved` / `checksum` (conforme decisão posterior) - -2. **Cell Stream** - - vetor contínuo com `width * height` células `u16`, little-endian; - - leitura linear favorece cache e descompressão simples. - -3. **Optional Chunks (future-proof)** - - bloco opcional de `eventTriggers`; - - bloco opcional de `spawnPoints`; - - bloco opcional de `navHints`. - -Packing de célula (`U16_PACKED_V1`): - -- `bits 0..9` => `visualId` -- `bits 10..14` => `collisionId` -- `bit 15` => `flag0` - -Decodificação de referência: - -- `visualId -> metatile visual table -> 4 subtiles (8x8) + palette/flip/priority` -- `collisionId -> collision/material table -> walk/solid/swim/damage/etc.` - -## Memory Notes for Active Window (`9` maps) - -Assumindo `64 KiB` por map bank: - -- `1` mapa residente: `64 KiB` -- `9` mapas residentes: `576 KiB` - -Capacidade por encoding dentro de `64 KiB`: - -- `u8`: `65,536` células (`256x256` máximo quadrado) -- `u16`: `32,768` células (`~181x181` máximo quadrado, ou retângulos equivalentes) -- `u32`: `16,384` células (`128x128` máximo quadrado) - -## Recommendation - -Adotar `Option B` como baseline para decisão: - -1. autoria em JSON orientada a IDs (`visualId`, `collisionId`, `flags`); -2. empacotamento determinístico para `U16_PACKED_V1` no build; -3. janela ativa de runtime limitada a `9` mapas com budget explícito; -4. extensão para `u32` somente via nova versão de encoding e evidência de necessidade. - -## Open Questions - -1. `collisionId` com `5 bits` (`32` classes) é suficiente para os biomas/projetos previstos? -2. `flag0` deve ser reservado para trigger rápido ou para variação visual contextual? -3. Quais chunks opcionais entram já em `V1` e quais ficam para `V2`? -4. O `map bank` seguirá estritamente `64 KiB` ou terá tamanho variável com metadado de capacidade? -5. Qual política de compressão do stream (`none`, `LZ4`, etc.) será padrão no packer? - -## Expected Follow-up - -1. Abrir `decision` em `docs/packer/decisions` fechando o encoding `U16_PACKED_V1`. -2. Propagar contrato de leitura para `docs/vm-arch`. -3. Definir no `docs/studio/specs` o schema de edição JSON correspondente. -4. Planejar PR de implementação (`packer` + `runtime`) com testes de roundtrip (`JSON -> BIN -> decode`). diff --git a/docs/packer/agendas/Variable Tile Bank Palette Serialization Agenda.md b/docs/packer/agendas/Variable Tile Bank Palette Serialization Agenda.md deleted file mode 100644 index bb1a1c9a..00000000 --- a/docs/packer/agendas/Variable Tile Bank Palette Serialization Agenda.md +++ /dev/null @@ -1,142 +0,0 @@ -# Variable Tile Bank Palette Serialization Agenda - -## Status - -Active - -## Domain Owner - -- `docs/packer` - -Cross-domain dependency: - -- `../runtime` - -## Purpose - -Decide whether `tile bank` payloads should keep serializing a fixed block of `64` palettes in v1, or evolve to serialize only the palettes actually authored by the asset. - -## Context - -The current `tile bank` contract is aligned between `packer` and `runtime`: - -- pixels are serialized as packed `u4`; -- palettes are serialized as `RGB565 u16`; -- `palette_count = 64`; -- payload size is derived from `ceil(width * height / 2) + (64 * 16 * 2)`. - -This means a `tile bank` with `1` authored palette still serializes `64` palette slots. Unused slots are currently zero-filled, which is valid for the runtime, but wastes cartridge space. - -The packer now exposes: - -- `metadata.palette_count = 64` -- `metadata.palette_authored = ` - -This makes the waste explicit, but does not remove it. - -## Problem - -The runtime-facing v1 contract favors fixed-size decode simplicity over cartridge efficiency. - -We need to decide whether: - -1. fixed `64` palette slots remain the normative contract for `tile bank`; -2. `palette_count` becomes variable and payload size shrinks to the authored set; -3. another staged strategy is better. - -## Options - -### Option A: Keep Fixed 64-Palette Serialization - -Keep the current contract unchanged: - -- `palette_count` remains `64`; -- every `tile bank` serializes `64 * 16 * 2 = 2048` bytes of palettes; -- authored palettes populate their indexed slots; -- unused slots are zero-filled. - -### Option B: Move to Variable Palette Serialization - -Evolve the contract so `tile bank` serializes only authored palettes: - -- `palette_count` becomes the authored count; -- payload size becomes `ceil(width * height / 2) + (palette_count * 16 * 2)`; -- runtime validates and decodes variable palette blocks. - -### Option C: Keep V1 Fixed, Design Variable Serialization for V2 - -Preserve the current runtime-facing v1 contract now, but explicitly open a v2 format/contract: - -- v1 stays fixed at `64`; -- v2 introduces variable palette serialization; -- packer and runtime keep clear compatibility boundaries. - -## Tradeoffs - -### Option A - -Pros: - -- no further runtime work; -- simplest decode path; -- current specs and tests stay valid. - -Cons: - -- every `tile bank` pays the full 2 KB palette cost; -- cartridge size is inflated for small authored palette sets; -- the metadata now exposes a mismatch between authored and serialized counts by design. - -### Option B - -Pros: - -- reduces cartridge size; -- makes `palette_count` semantically tighter; -- removes fixed empty palette padding from the payload. - -Cons: - -- requires coordinated changes in `packer`, `runtime`, specs, and tests; -- changes the `size` / `decoded_size` formulas; -- raises compatibility and migration questions for existing assets and cartridges. - -### Option C - -Pros: - -- keeps current work stable; -- makes room for a cleaner future contract; -- avoids mixing optimization work into the current tile-bank rollout. - -Cons: - -- known waste remains in v1; -- adds future format/version management work. - -## Recommendation - -Recommendation for now: `Option C`. - -Reasoning: - -- the current fixed-size contract is already implemented and aligned; -- the waste is real, but it is not a correctness bug; -- changing it now would reopen a cross-domain runtime contract that was just stabilized; -- if we want variable palette serialization, it should be introduced deliberately as a versioned follow-up, not as an incidental tweak. - -## Open Questions - -1. Should variable palette serialization be introduced as a new `tile bank` payload version, or as an incompatible change to the current one? -2. If `palette_count` becomes variable, should runtime still materialize a 64-slot bank in memory, or truly shrink the resident representation too? -3. Should palette slot identity remain sparse by authored `index`, or should serialization canonicalize into a dense runtime block? -4. Which domain owns the compatibility story for existing cartridges: `packer`, `runtime`, or `shipper`? - -## Expected Follow-up - -If the team wants to eliminate the fixed 64-palette padding: - -1. create a corresponding runtime agenda/decision; -2. define the versioning and compatibility story; -3. update `packer` and `runtime` specs together; -4. then plan code changes in both domains. diff --git a/docs/packer/decisions/README.md b/docs/packer/decisions/README.md deleted file mode 100644 index 64e73b83..00000000 --- a/docs/packer/decisions/README.md +++ /dev/null @@ -1,53 +0,0 @@ -# Packer Decisions - -This directory contains packer decision records that still need propagation. - -Current retained set: - -- none - -The current packer decision wave has already been consolidated into: - -- normative specifications under [`../specs/`](../specs/) -- didactic material under [`../learn/`](../learn/) - -## Purpose - -A decision record is the bridge between packer discussion and packer execution. - -Use this directory to capture: - -- what was decided, -- why that direction was chosen, -- which constraints now apply, -- what remains intentionally undecided, -- which specs, plans, tests, or implementations must be updated. - -A decision should be stable enough that a spec or implementation worker can act on it without reconstructing the original debate. - -## Expected Format - -A packer decision should usually include: - -1. Title -2. Status -3. Date or Cycle -4. Context -5. Decision -6. Invariants and Constraints -7. Explicit Non-Decisions -8. Propagation Targets -9. Validation Notes or Examples - -## Writing Rules - -- State the adopted decision early and clearly. -- Write in stable language, not in exploratory tone. -- Capture architectural constraints explicitly. -- Record what is still not decided so later work does not guess. -- Point to the exact packer specs, PRs, or code areas that need propagation. - -## Implementation Rule - -If implementation work reveals a missing decision, do not infer it. -Return the issue to agenda or decision review. diff --git a/docs/packer/learn/README.md b/docs/packer/learn/README.md deleted file mode 100644 index 2f8e225b..00000000 --- a/docs/packer/learn/README.md +++ /dev/null @@ -1,59 +0,0 @@ -# Packer Learn - -This directory contains didactic packer knowledge. - -## Purpose - -`learn/` exists to teach, not merely to store historical leftovers. - -Use it to: - -- explain packer architecture in a way new contributors can absorb quickly, -- consolidate conclusions from completed decisions and PRs, -- document common pitfalls and anti-patterns, -- connect normative specs to practical reasoning and implementation reality. - -## What Belongs Here - -A `learn` artifact should usually include: - -1. the original problem, -2. the decision that resolved it, -3. the implemented or specified final model, -4. practical examples, -5. common mistakes and warnings, -6. links to the relevant specs and PRs. - -Good `learn` material reduces onboarding time and prevents the same architectural confusion from repeating. - -## Writing Rules - -- Prefer didactic structure over chronological accumulation. -- Explain why the model exists, not only what it is. -- Keep terminology aligned with packer specs. -- Refactor older material when the directory starts feeling like a document graveyard. - -## Refactor Rule - -This directory should be periodically reorganized for better presentation. - -If content grows, prefer: - -- thematic grouping, -- overview documents, -- explicit learning paths, -- and consolidation of duplicated explanations. - -The goal is a maintainable learning surface, not a passive archive. - -## Current Learning Path - -Start here: - -1. [`mental-model-packer.md`](./mental-model-packer.md) -2. [`mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md) -3. [`foundations-workspace-runtime-and-build.md`](./foundations-workspace-runtime-and-build.md) -4. [`runtime-ownership-and-studio-boundary.md`](./runtime-ownership-and-studio-boundary.md) -5. [`mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md) -6. [`pack-wizard-summary-validation-and-pack-execution.md`](./pack-wizard-summary-validation-and-pack-execution.md) -7. [`tile-bank-packing-contract.md`](./tile-bank-packing-contract.md) diff --git a/docs/packer/learn/foundations-workspace-runtime-and-build.md b/docs/packer/learn/foundations-workspace-runtime-and-build.md deleted file mode 100644 index f384b38a..00000000 --- a/docs/packer/learn/foundations-workspace-runtime-and-build.md +++ /dev/null @@ -1,91 +0,0 @@ -# Foundations: Workspace, Runtime, and Build - -## Original Problem - -The packer domain accumulated a long implementation wave covering workspace control, asset identity, scanning, mutations, diagnostics, deterministic planning, runtime snapshots, and cache reuse. - -The historical PR chain was useful while the repository was converging, but it stopped being a good onboarding surface: - -- too much knowledge was spread across execution slices; -- too much reasoning depended on chronological reconstruction; -- too little of that knowledge was available as one stable mental model. - -## Consolidated Decision - -The stable packer foundation is: - -1. the workspace stays open and filesystem-first; -2. `assets/.prometeu/index.json` owns managed identity and inclusion state; -3. each asset root is anchored by `asset.json`; -4. the packer runtime serves coherent snapshot-backed reads; -5. writes are coordinated by the packer and become visible after durable commit; -6. build outputs are derived deterministically from validated, packer-owned state. - -## Final Model - -### 1. Workspace and Identity - -- `asset_id` is the stable managed identifier used for ordering, inclusion, and runtime-facing tables; -- `asset_uuid` is the local identity anchor that helps reconcile the same logical asset across path movement; -- `asset_name` is the logical human-facing identifier and is not a substitute for managed identity; -- `asset.json` describes authoring intent, not registry-owned bookkeeping. - -### 2. Read and Write Authority - -- normal reads come from a coherent runtime snapshot rather than from ad hoc filesystem scans; -- the filesystem still matters because it remains the durable authoring surface; -- writes flow through packer-owned preview/apply semantics and one project-scoped serialized lane. - -### 3. Deterministic Build Path - -- only validated managed assets enter the build path; -- asset ordering is deterministic by increasing `asset_id`; -- runtime-facing artifacts are emitted from canonical packer-owned planning and materialization rules; -- companion artifacts mirror build authority rather than define parallel truth. - -### 4. Runtime Snapshot Evolution - -The later runtime wave refined the first foundation: - -- runtime state became explicitly project-scoped; -- snapshot updates happen after successful write commit; -- query services read from that runtime state; -- cache layers exist to accelerate the same ownership model, not to bypass it. - -## Examples - -### Example: Why relocation does not create a new asset - -If an asset root moves on disk, the packer should preserve the managed identity when the move is a relocation of the same logical asset. - -That is why: - -- the registry owns stable managed identity; -- path is mutable operational state; -- relocation updates root tracking without inventing a new `asset_id`. - -### Example: Why filesystem order cannot define build order - -Two equivalent workspaces may be traversed in different directory order. -The build must still emit the same `asset_table` and payload layout. - -That is why deterministic ordering is tied to managed identity, not traversal order. - -## Common Pitfalls and Anti-Patterns - -- Treating `asset_name` as if it were a stable runtime identifier. -- Moving registry-owned fields into `asset.json`. -- Recomputing semantic read models directly from Studio-side filesystem heuristics. -- Letting build order depend on traversal order, cache insertion order, or UI ordering. -- Treating cache state as semantic authority instead of as an optimization. - -## References - -- Specs: - - [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md) - - [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) - - [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) - - [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) -- Related learn: - - [`./mental-model-packer.md`](./mental-model-packer.md) - - [`./mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md) diff --git a/docs/packer/learn/mental-model-asset-identity-and-runtime-contract.md b/docs/packer/learn/mental-model-asset-identity-and-runtime-contract.md deleted file mode 100644 index 8dae778f..00000000 --- a/docs/packer/learn/mental-model-asset-identity-and-runtime-contract.md +++ /dev/null @@ -1,95 +0,0 @@ -# Asset Identity and Runtime Contract - -This document explains the point that is easiest to get subtly wrong: - -- `asset_id` is the stable artifact identity; -- `asset_name` is still a logical code-facing reference. - -If you flatten those two concepts into one, the architecture starts drifting immediately. - -## The Stable Side: `asset_id` - -`asset_id` is allocated by the packer registry. - -It is stable within the project and appears in runtime-facing artifacts. - -Why this matters: - -- preload uses `asset_id`; -- artifact identity survives move and rename; -- build outputs remain structurally stable even when authoring layout changes. - -`asset_id` is the answer to: - -> “Is this the same asset as before?” - -## The Logical Side: `asset_name` - -`asset_name` remains useful because game-facing code and runtime APIs still refer to assets by name in normal flows. - -Why this matters: - -- authors need a readable label; -- game code usually references assets semantically, not by integer literal; -- runtime lookup still uses names in parts of the current operational surface. - -`asset_name` is the answer to: - -> “What do humans and source code call this asset?” - -## Why Not Use Only One Of Them? - -If you use only `asset_name`: - -- rename becomes identity breakage; -- preload/bootstrap integrity becomes fragile; -- build artifacts depend too much on mutable author intent. - -If you use only `asset_id` everywhere today: - -- source code becomes less ergonomic; -- authoring workflows become harder to read; -- the current runtime/game-facing API model would need stronger compile-time lowering infrastructure. - -So the current architecture intentionally keeps both: - -- stable identity for artifacts; -- logical naming for authoring and API usage. - -## What Actually Happens In The Artifact? - -The runtime-facing asset table carries both: - -- `asset_id` -- `asset_name` - -But they play different roles. - -`asset_id`: - -- defines stable identity; -- is used for preload/bootstrap integrity. - -`asset_name`: - -- stays in the table as descriptive/API-facing metadata; -- supports name-based lookup where that still exists. - -## Why This Is Still Not The End Of The Story - -There is still an open language/toolchain question: - -- should source-level asset references remain name-based forever? -- or should the compiler eventually lower known references to stable IDs or resource handles? - -That is a separate problem from the packer artifact identity model. -It belongs to language/frontend and runtime API design, not to the core packer identity rules. - -## Practical Rule - -When reading or implementing packer behavior, use this checklist: - -- if the question is about stable artifact identity, think `asset_id`; -- if the question is about source naming or human-facing lookup, think `asset_name`; -- if the question is about preload/bootstrap correctness, prefer `asset_id`; -- if the question is about runtime/game API ergonomics, `asset_name` may still be intentionally present. diff --git a/docs/packer/learn/mental-model-metadata-convergence-and-runtime-sink.md b/docs/packer/learn/mental-model-metadata-convergence-and-runtime-sink.md deleted file mode 100644 index b4777a20..00000000 --- a/docs/packer/learn/mental-model-metadata-convergence-and-runtime-sink.md +++ /dev/null @@ -1,78 +0,0 @@ -# Metadata Convergence and Runtime Sink (`AssetEntry.metadata`) - -## Original Problem - -Packer authoring contracts may carry metadata from different concerns: - -- asset/runtime contract metadata; -- codec-related metadata; -- pipeline-derived metadata generated during materialization. - -Without an explicit convergence rule, teams drift into ambiguous behavior: - -- runtime readers are unsure where effective values must be read; -- metadata merge behavior becomes accidental and non-deterministic; -- payload slicing fields can be confused with internal indexing offsets. - -## Consolidated Decision - -The accepted direction is: - -1. all runtime-consumable metadata converges to a single sink: `AssetEntry.metadata`; -2. source segmentation in `asset.json` is allowed for authoring ergonomics; -3. build/materialization must normalize sources deterministically; -4. collisions require explicit contract rules or must fail build; -5. `AssetEntry.offset`/`AssetEntry.size` keep payload slicing semantics and do not replace internal pipeline indexing. - -## Final Model - -Think in two layers: - -- **Authoring layer**: source metadata may be segmented by concern; -- **Runtime layer**: one effective metadata map in each emitted asset entry. - -Practical rule for runtime consumers: - -- if the value is runtime-consumable metadata, read it from `AssetEntry.metadata`. - -Practical rule for packer implementation: - -- normalize all relevant metadata sources into `AssetEntry.metadata` during build; -- keep normalization deterministic and testable. - -## Example (Audio Bank Indexing) - -Illustrative normalized metadata shape: - -```json -{ - "metadata": { - "sample_rate": 22050, - "channels": 1, - "samples": { - "1": { "offset": 0, "length": 100 } - }, - "codec": { - "parity": 10 - } - } -} -``` - -In this model: - -- `samples[*].offset/length` are internal indexing values for the audio payload contract; -- they are not the same thing as `AssetEntry.offset/size` in the asset table. - -## Common Pitfalls and Anti-Patterns - -- Treating segmented declaration metadata as multiple runtime sinks. -- Allowing silent key overwrite when two metadata sources collide. -- Mixing payload slicing semantics (`asset_table[].offset/size`) with internal indexing semantics (`metadata.samples[*].offset/length`). -- Documenting convergence behavior only in code comments and not in normative specs. - -## References - -- Spec: [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md) -- Spec: [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) -- Related learn: [`./tile-bank-packing-contract.md`](./tile-bank-packing-contract.md) diff --git a/docs/packer/learn/mental-model-packer.md b/docs/packer/learn/mental-model-packer.md deleted file mode 100644 index 79e713e8..00000000 --- a/docs/packer/learn/mental-model-packer.md +++ /dev/null @@ -1,87 +0,0 @@ -# Packer Mental Model - -The packer is not a cartridge shipper, not a runtime reader, and not a random file janitor. -It is the system that turns an asset workspace into stable asset artifacts. - -The easiest way to understand it is through five questions. - -## 1. What is the unit of management? - -The unit is the managed asset root. - -One managed asset: - -- lives in one asset root directory; -- has one anchor `asset.json`; -- may include many internal files as inputs. - -This is why an atlas, image bank, or grouped sound bundle can still be one asset. -The managed asset is the output unit, not each source file. - -## 2. Where is the source of truth? - -There are two different truths for two different jobs: - -- `assets/.prometeu/index.json` tells the packer which assets are officially managed; -- each `asset.json` tells the packer what that asset declares locally. - -This split matters. -Without it, copy/move/register flows become ambiguous very quickly. - -## 3. What is the difference between `asset_id` and `asset_name`? - -They are not the same thing. - -`asset_id` is the stable identity. -It survives moves and renames. - -`asset_name` is the logical reference label. -It is the thing source code and runtime-facing APIs may still use today. - -That means: - -- renaming `asset_name` is not an identity change; -- but it can still be an API-visible change. - -This is the most important distinction to keep in your head while reading the packer and runtime contracts. - -## 4. What is the runtime-facing artifact? - -`assets.pa`. - -That is the artifact the runtime reads. -It is authoritative for runtime-facing asset metadata. - -Companion JSON files exist for Studio and tooling, but they do not replace the contract inside `assets.pa`. - -## 5. Why is determinism so important? - -Because the packer is not just a converter. -It is part of the contract chain between authoring, Studio, shipping, and runtime. - -If equivalent inputs can produce different outputs accidentally, then: - -- debugging becomes harder; -- caching becomes unreliable; -- artifact review gets noisy; -- runtime compatibility becomes more fragile. - -That is why the packer decisions keep preferring: - -- explicit declaration over inference; -- stable identity over convenience; -- canonical serialization over incidental serializer behavior; -- preview/apply over silent mutation. - -## How To Read The Packer Specs - -Use this order: - -1. domain and boundary -2. workspace and identity -3. asset declaration -4. build artifacts -5. diagnostics and Studio integration -6. versioning and trust - -That sequence moves from “what the packer is” to “how it behaves” to “how it stays safe over time”. diff --git a/docs/packer/learn/pack-wizard-summary-validation-and-pack-execution.md b/docs/packer/learn/pack-wizard-summary-validation-and-pack-execution.md deleted file mode 100644 index a92304d3..00000000 --- a/docs/packer/learn/pack-wizard-summary-validation-and-pack-execution.md +++ /dev/null @@ -1,118 +0,0 @@ -# Pack Wizard: Summary, Validation, and Pack Execution - -## Original Problem - -The Studio-side wizard was already accepted as a shell over packer-owned operations, but the packer side still needed one coherent story for: - -1. what `summary` means; -2. what `validation` means; -3. how `packWorkspace(...)` executes without trusting stale UI state or live filesystem rereads. - -The historical agenda, decisions, and PRs solved this in slices. -This document keeps the final model in one place. - -## Consolidated Decision - -The first-wave `Pack Wizard` contract is phase-based and fully packer-owned: - -1. `summary` is a fast snapshot-backed preflight view; -2. `validation` is a snapshot-backed gate over the same active pack set; -3. `packWorkspace(...)` is the only artifact-emitting wizard operation; -4. execution reruns the gate on a fresh frozen snapshot; -5. outputs are staged before promotion into final `build/` locations. - -The active pack set is always: - -`registered + included in build` - -## Final Model - -### 1. Summary - -`summary` is not a build preview. -It is a quick packer-owned view of the current active pack set. - -First-wave payload: - -- total included asset count; -- one per-asset list with: - - `assetId` - - `assetName` - - `assetFamily` - - `minArtifactCount` - - `maxArtifactCount` - - `lastModified` - -### 2. Validation - -`validation` evaluates the same pack set as `summary`, but its job is to answer a different question: - -Can packing begin? - -First-wave rule: - -- only `blocking` diagnostics fail validation; -- warnings are visible elsewhere, but they are not part of the first validation gate contract. - -Primary payload: - -- one per-asset list containing only assets with blocking diagnostics. - -### 3. Pack Execution - -`packWorkspace(...)` is a write-lane operation. -It does not trust that earlier summary or validation responses are still current. - -The first-wave execution path is: - -1. create a fresh execution snapshot; -2. rerun the gate on that snapshot; -3. materialize outputs from frozen in-memory inputs; -4. write to `build/.staging//`; -5. promote to final `build/` outputs only after coherent success. - -### 4. Result Semantics - -The final result must distinguish: - -- gate failure before emission; -- execution/materialization failure; -- persistence/promotion failure; -- successful publication. - -Studio should be able to render `Packing` and `Result` from packer-owned outcome semantics alone. - -## Examples - -### Example: Why green validation is not enough - -Validation may have been green a few seconds earlier. -If the workspace changes before pack execution begins, the packer still must rerun the gate on a fresh frozen snapshot. - -That protects the operation from: - -- stale UI assumptions; -- filesystem drift; -- accidental emission from no-longer-valid inputs. - -### Example: Why summary excludes unregistered assets - -The wizard is a pack-set workflow, not a generic workspace inspection screen. -Unregistered or excluded assets may matter to other tooling, but they are not explicit summary items in the first-wave wizard contract. - -## Common Pitfalls and Anti-Patterns - -- Treating `summary` as if it were an emitted-artifact preview. -- Running validation over a broader set than `registered + included in build`. -- Letting non-blocking warnings fail the first-wave validation gate. -- Reading live filesystem bytes after frozen execution materialization has started. -- Publishing final `build/` outputs before the operation has reached a coherent success point. - -## References - -- Specs: - - [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) - - [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) -- Cross-domain: - - [`../../studio/learn/pack-wizard-shell.md`](../../studio/learn/pack-wizard-shell.md) - - [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md) diff --git a/docs/packer/learn/runtime-ownership-and-studio-boundary.md b/docs/packer/learn/runtime-ownership-and-studio-boundary.md deleted file mode 100644 index 7b27ff9e..00000000 --- a/docs/packer/learn/runtime-ownership-and-studio-boundary.md +++ /dev/null @@ -1,88 +0,0 @@ -# Runtime Ownership and Studio Boundary - -## Original Problem - -Once the packer stopped being just a set of direct filesystem helpers, the repository needed a clear answer for three things: - -1. who owns operational asset semantics; -2. how concurrent reads and writes stay coherent; -3. how Studio consumes packer state without duplicating domain logic. - -Without that boundary, the system would drift into split-brain behavior between packer services and Studio UI code. - -## Consolidated Decision - -The packer is the semantic owner of operational asset state. -Studio is a consumer of packer responses, commands, and events. - -The stable boundary is: - -- filesystem-first authoring workspace; -- project-scoped runtime snapshot for reads; -- single-writer semantic lane per project for commit-bearing operations; -- packer-native observability with causal ordering; -- Studio adapters that translate for presentation but do not invent semantics. - -## Final Model - -### 1. Filesystem-First Runtime - -- the workspace on disk remains the durable source of truth; -- the runtime snapshot is an operational projection used for coherent reads and write coordination; -- divergence between runtime state and filesystem state must become explicit packer state, not silent repair. - -### 2. Concurrency Model - -- `read/read` may run concurrently when both observe one coherent snapshot; -- `read/write` must not expose torn intermediate state; -- `write/write` on the same project is serialized; -- build-bearing operations share the same project-scoped coordination story. - -### 3. Event Ownership - -- packer events are authoritative for lifecycle, progress, and outcomes; -- each logical operation carries stable causality through `operation_id` and monotonic `sequence`; -- sinks may coalesce noisy progress updates, but terminal lifecycle events remain observable. - -### 4. Studio Adapter Rule - -- Studio may remap packer data into workspace and shell view models; -- Studio must not recreate packer summaries, mutation semantics, or reconcile semantics from local heuristics; -- adapter code is translational, not semantic-authoritative. - -## Examples - -### Example: Mutation preview in Studio - -The preview may be rendered in Studio-specific components, but the semantic meaning of: - -- blockers, -- warnings, -- registry mutations, -- filesystem mutations, -- final apply outcome - -must still come from the packer. - -### Example: Activity and progress - -If the UI shows a simplified progress bar or activity feed, that is fine. -What is not fine is for Studio to infer a successful final outcome without a packer-native terminal event or response. - -## Common Pitfalls and Anti-Patterns - -- Rebuilding packer summaries from navigator rows or local filesystem scans. -- Treating adapter code as a second owner of mutation or reconcile rules. -- Hiding divergence by silently refreshing state without surfacing the transition. -- Allowing same-project writes to race because the caller "already validated" earlier. -- Collapsing event causality into UI-local state that cannot be replayed or tested outside Studio. - -## References - -- Specs: - - [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) - - [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) -- Cross-domain: - - [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md) -- Related learn: - - [`./foundations-workspace-runtime-and-build.md`](./foundations-workspace-runtime-and-build.md) diff --git a/docs/packer/learn/tile-bank-packing-contract.md b/docs/packer/learn/tile-bank-packing-contract.md deleted file mode 100644 index ba204c26..00000000 --- a/docs/packer/learn/tile-bank-packing-contract.md +++ /dev/null @@ -1,116 +0,0 @@ -# Tile Bank Packing Contract - -## Original Problem - -After the generic pack execution boundary was closed, `tile bank` still lacked one explicit producer contract. - -The repository needed to settle: - -1. how selected tile artifacts become one packed payload; -2. how palette identity is declared and normalized; -3. which runtime fields are derived for `AssetEntry`; -4. which structural problems block packing before byte emission. - -## Consolidated Decision - -The first-wave `tile bank` producer contract is: - -1. one canonical `TILES/indexed_v1` payload per asset; -2. `1 artifact = 1 tile`; -3. artifacts are normalized by explicit `artifacts[*].index`; -4. the emitted sheet is fixed at `256 x 256` and row-major; -5. tile pixels are packed `u4`; -6. bank palettes are emitted as `RGB565` `u16`; -7. palette declarations use explicit `{ index, palette }`; -8. structural diagnostics are produced early in walker/materialization and therefore participate in validation. - -## Final Model - -### 1. Payload Shape - -The payload is not a concatenation of artifact-local binaries. -It is one canonical bank raster: - -1. packed `u4` pixel indices for the full sheet; -2. one `64 * 16 * 2` palette block. - -### 2. Artifact and Tile Identity - -- artifacts are normalized by ascending declared `index`; -- `tile_id` matches the normalized artifact index; -- placement is row-major in the fixed sheet; -- v1 capacities depend on `tile_size`: - - `8 -> 1024` - - `16 -> 256` - - `32 -> 64` - -### 3. Palette Contract - -- palette identity is semantic, not positional; -- ordering is ascending numeric `index`, never raw list order; -- any tile may be rendered with any bank palette at runtime; -- palette selection is a draw-time concern, not an embedded per-tile payload field. - -### 4. Metadata Contract - -`AssetEntry.metadata` keeps runtime-required fields readable at the root while preserving segmented subtrees: - -- `output.metadata -> metadata` -- `output.codec_configuration -> metadata.codec` -- `output.pipeline -> metadata.pipeline` - -For tile banks, that means root readability for values such as: - -- `tile_size` -- `width` -- `height` -- `palette_count` - -### 5. Validation Boundary - -Tile-bank structural issues belong in the walker/materialization path, not in a late pack-only surprise phase. - -Blocking conditions include: - -- duplicate artifact indices; -- gaps in normalized artifact indices; -- fixed-sheet overflow; -- missing palettes; -- palette count above `64`; -- malformed palette declarations; -- missing required metadata; -- normalization failure. - -Fragile tile indices are warnings in the first wave, not blockers by themselves. - -## Examples - -### Example: Why palette index must be explicit - -If palette identity depends on array position, a harmless editorial reorder can silently change runtime meaning. - -Using `{ index, palette }` makes semantic identity reviewable and stable. - -### Example: Why validation must see tile-bank structure early - -If duplicate artifact indices are discovered only during final byte emission, the wizard reaches `Packing` too late. -The correct behavior is for validation to surface the blocker before emission begins, and for pack execution to rerun that same gate on a fresh execution snapshot. - -## Common Pitfalls and Anti-Patterns - -- Treating artifact declaration order as semantic tile identity. -- Packing per-artifact fragments instead of one canonical sheet. -- Embedding palette choice per tile in the packed payload. -- Flattening all metadata into one ambiguous map. -- Discovering tile-bank blockers only during late byte emission. - -## References - -- Specs: - - [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md) - - [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) -- Cross-domain: - - [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md) - - [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md) -- Related learn: - - [`./mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md) diff --git a/docs/packer/pull-requests/README.md b/docs/packer/pull-requests/README.md deleted file mode 100644 index f834d9f8..00000000 --- a/docs/packer/pull-requests/README.md +++ /dev/null @@ -1,68 +0,0 @@ -# Packer Pull Requests - -This directory contains self-contained packer change proposals for review. - -Current retained set: - -- none - -The previous execution wave has already been consolidated into [`../learn/`](../learn/) and propagated into [`../specs/`](../specs/). - -## Purpose - -A pull request document packages a packer change as an executable plan before final integration. - -Use this directory when a change: - -- touches multiple documents or code paths, -- changes packer architecture or semantics, -- needs explicit acceptance criteria, -- affects diagnostics, build outputs, registry rules, or shipper boundaries, -- should be reviewed before editing the final normative corpus or implementation. - -## Required Properties - -Every pull request document must be self-contained. - -A reviewer should be able to understand: - -- the problem, -- the target state, -- the execution method, -- the acceptance bar, -- and the validation surface. - -## Required Sections - -Each packer pull request should include, at minimum: - -1. Briefing -2. Target -3. Method -4. Acceptance Criteria -5. Tests or Validation - -Recommended additional sections: - -6. Motivation -7. Scope -8. Non-Goals -9. Affected Documents -10. Open Questions - -## Writing Rules - -- Keep the proposal self-contained and reviewable. -- Separate architectural reasoning from implementation detail. -- Make packer outputs and contracts explicit. -- Do not smuggle unresolved product or architecture choices into implementation steps. -- If a required decision is missing, stop and raise it instead of guessing. - -## Review Rule - -A pull request may plan code and spec consequences, but it must not replace a missing decision record. - -## Production Sequence - -When a new execution wave starts, add only the PRs that still represent pending work. -Do not repopulate this directory with already-absorbed historical implementation slices. diff --git a/docs/compiler/pbs/specs/1. Language Charter.md b/docs/specs/compiler-languages/pbs/1. Language Charter.md similarity index 100% rename from docs/compiler/pbs/specs/1. Language Charter.md rename to docs/specs/compiler-languages/pbs/1. Language Charter.md diff --git a/docs/compiler/pbs/specs/10. Memory and Lifetime Specification.md b/docs/specs/compiler-languages/pbs/10. Memory and Lifetime Specification.md similarity index 100% rename from docs/compiler/pbs/specs/10. Memory and Lifetime Specification.md rename to docs/specs/compiler-languages/pbs/10. Memory and Lifetime Specification.md diff --git a/docs/compiler/pbs/specs/11. AST Specification.md b/docs/specs/compiler-languages/pbs/11. AST Specification.md similarity index 100% rename from docs/compiler/pbs/specs/11. AST Specification.md rename to docs/specs/compiler-languages/pbs/11. AST Specification.md diff --git a/docs/compiler/pbs/specs/12. Diagnostics Specification.md b/docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md similarity index 100% rename from docs/compiler/pbs/specs/12. Diagnostics Specification.md rename to docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md diff --git a/docs/compiler/pbs/specs/13. Lowering IRBackend Specification.md b/docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md similarity index 100% rename from docs/compiler/pbs/specs/13. Lowering IRBackend Specification.md rename to docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md diff --git a/docs/compiler/pbs/specs/2. Governance and Versioning.md b/docs/specs/compiler-languages/pbs/2. Governance and Versioning.md similarity index 100% rename from docs/compiler/pbs/specs/2. Governance and Versioning.md rename to docs/specs/compiler-languages/pbs/2. Governance and Versioning.md diff --git a/docs/compiler/pbs/specs/3. Core Syntax Specification.md b/docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md similarity index 100% rename from docs/compiler/pbs/specs/3. Core Syntax Specification.md rename to docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md diff --git a/docs/compiler/pbs/specs/4. Static Semantics Specification.md b/docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md similarity index 100% rename from docs/compiler/pbs/specs/4. Static Semantics Specification.md rename to docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md diff --git a/docs/compiler/pbs/specs/5. Manifest, Stdlib, and SDK Resolution Specification.md b/docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md similarity index 100% rename from docs/compiler/pbs/specs/5. Manifest, Stdlib, and SDK Resolution Specification.md rename to docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md diff --git a/docs/compiler/pbs/specs/6. VM-owned vs Host-backed.md b/docs/specs/compiler-languages/pbs/6. VM-owned vs Host-backed.md similarity index 100% rename from docs/compiler/pbs/specs/6. VM-owned vs Host-backed.md rename to docs/specs/compiler-languages/pbs/6. VM-owned vs Host-backed.md diff --git a/docs/compiler/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md b/docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md similarity index 100% rename from docs/compiler/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md rename to docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md diff --git a/docs/compiler/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md b/docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md similarity index 100% rename from docs/compiler/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md rename to docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md diff --git a/docs/compiler/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md b/docs/specs/compiler-languages/pbs/7. Cartridge Manifest and Runtime Capabilities Specification.md similarity index 100% rename from docs/compiler/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md rename to docs/specs/compiler-languages/pbs/7. Cartridge Manifest and Runtime Capabilities Specification.md diff --git a/docs/compiler/pbs/specs/8. Stdlib Environment Packaging and Loading Specification.md b/docs/specs/compiler-languages/pbs/8. Stdlib Environment Packaging and Loading Specification.md similarity index 100% rename from docs/compiler/pbs/specs/8. Stdlib Environment Packaging and Loading Specification.md rename to docs/specs/compiler-languages/pbs/8. Stdlib Environment Packaging and Loading Specification.md diff --git a/docs/compiler/pbs/specs/9. Dynamic Semantics Specification.md b/docs/specs/compiler-languages/pbs/9. Dynamic Semantics Specification.md similarity index 100% rename from docs/compiler/pbs/specs/9. Dynamic Semantics Specification.md rename to docs/specs/compiler-languages/pbs/9. Dynamic Semantics Specification.md diff --git a/docs/compiler/pbs/specs/README.md b/docs/specs/compiler-languages/pbs/README.md similarity index 100% rename from docs/compiler/pbs/specs/README.md rename to docs/specs/compiler-languages/pbs/README.md diff --git a/docs/compiler/general/specs/13. Conformance Test Specification.md b/docs/specs/compiler/13. Conformance Test Specification.md similarity index 100% rename from docs/compiler/general/specs/13. Conformance Test Specification.md rename to docs/specs/compiler/13. Conformance Test Specification.md diff --git a/docs/compiler/general/specs/14. Name Resolution and Module Linking Specification.md b/docs/specs/compiler/14. Name Resolution and Module Linking Specification.md similarity index 100% rename from docs/compiler/general/specs/14. Name Resolution and Module Linking Specification.md rename to docs/specs/compiler/14. Name Resolution and Module Linking Specification.md diff --git a/docs/compiler/general/specs/15. Bytecode and PBX Mapping Specification.md b/docs/specs/compiler/15. Bytecode and PBX Mapping Specification.md similarity index 100% rename from docs/compiler/general/specs/15. Bytecode and PBX Mapping Specification.md rename to docs/specs/compiler/15. Bytecode and PBX Mapping Specification.md diff --git a/docs/compiler/general/specs/16. Runtime Execution and Initialization Specification.md b/docs/specs/compiler/16. Runtime Execution and Initialization Specification.md similarity index 100% rename from docs/compiler/general/specs/16. Runtime Execution and Initialization Specification.md rename to docs/specs/compiler/16. Runtime Execution and Initialization Specification.md diff --git a/docs/compiler/general/specs/17. Compatibility and Evolution Policy.md b/docs/specs/compiler/17. Compatibility and Evolution Policy.md similarity index 100% rename from docs/compiler/general/specs/17. Compatibility and Evolution Policy.md rename to docs/specs/compiler/17. Compatibility and Evolution Policy.md diff --git a/docs/compiler/general/specs/18. Standard Library Surface Specification.md b/docs/specs/compiler/18. Standard Library Surface Specification.md similarity index 100% rename from docs/compiler/general/specs/18. Standard Library Surface Specification.md rename to docs/specs/compiler/18. Standard Library Surface Specification.md diff --git a/docs/compiler/general/specs/19. Verification and Safety Checks Specification.md b/docs/specs/compiler/19. Verification and Safety Checks Specification.md similarity index 100% rename from docs/compiler/general/specs/19. Verification and Safety Checks Specification.md rename to docs/specs/compiler/19. Verification and Safety Checks Specification.md diff --git a/docs/compiler/general/specs/20. IRBackend to IRVM Lowering Specification.md b/docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md similarity index 100% rename from docs/compiler/general/specs/20. IRBackend to IRVM Lowering Specification.md rename to docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md diff --git a/docs/compiler/general/specs/21. IRVM Optimization Pipeline Specification.md b/docs/specs/compiler/21. IRVM Optimization Pipeline Specification.md similarity index 100% rename from docs/compiler/general/specs/21. IRVM Optimization Pipeline Specification.md rename to docs/specs/compiler/21. IRVM Optimization Pipeline Specification.md diff --git a/docs/compiler/general/specs/22. Backend Spec-to-Test Conformance Matrix.md b/docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md similarity index 100% rename from docs/compiler/general/specs/22. Backend Spec-to-Test Conformance Matrix.md rename to docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md diff --git a/docs/compiler/general/specs/README.md b/docs/specs/compiler/README.md similarity index 100% rename from docs/compiler/general/specs/README.md rename to docs/specs/compiler/README.md diff --git a/docs/packer/specs/1. Domain and Artifact Boundary Specification.md b/docs/specs/packer/1. Domain and Artifact Boundary Specification.md similarity index 100% rename from docs/packer/specs/1. Domain and Artifact Boundary Specification.md rename to docs/specs/packer/1. Domain and Artifact Boundary Specification.md diff --git a/docs/packer/specs/2. Workspace, Registry, and Asset Identity Specification.md b/docs/specs/packer/2. Workspace, Registry, and Asset Identity Specification.md similarity index 100% rename from docs/packer/specs/2. Workspace, Registry, and Asset Identity Specification.md rename to docs/specs/packer/2. Workspace, Registry, and Asset Identity Specification.md diff --git a/docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md b/docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md similarity index 100% rename from docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md rename to docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md diff --git a/docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md b/docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md similarity index 100% rename from docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md rename to docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md diff --git a/docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md b/docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md similarity index 100% rename from docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md rename to docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md diff --git a/docs/packer/specs/6. Versioning, Migration, and Trust Model Specification.md b/docs/specs/packer/6. Versioning, Migration, and Trust Model Specification.md similarity index 100% rename from docs/packer/specs/6. Versioning, Migration, and Trust Model Specification.md rename to docs/specs/packer/6. Versioning, Migration, and Trust Model Specification.md diff --git a/docs/packer/specs/README.md b/docs/specs/packer/README.md similarity index 79% rename from docs/packer/specs/README.md rename to docs/specs/packer/README.md index e9c304ca..c3a13127 100644 --- a/docs/packer/specs/README.md +++ b/docs/specs/packer/README.md @@ -56,12 +56,12 @@ If a spec edit would require guessing an unresolved design choice, stop and surf The current packer core corpus is: -1. [`1. Domain and Artifact Boundary Specification.md`](./1.%20Domain%20and%20Artifact%20Boundary%20Specification.md) -2. [`2. Workspace, Registry, and Asset Identity Specification.md`](./2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) -3. [`3. Asset Declaration and Virtual Asset Contract Specification.md`](./3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md) -4. [`4. Build Artifacts and Deterministic Packing Specification.md`](./4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) -5. [`5. Diagnostics, Operations, and Studio Integration Specification.md`](./5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) -6. [`6. Versioning, Migration, and Trust Model Specification.md`](./6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md) +1. [`1. Domain and Artifact Boundary Specification.md`](1.%20Domain%20and%20Artifact%20Boundary%20Specification.md) +2. [`2. Workspace, Registry, and Asset Identity Specification.md`](2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) +3. [`3. Asset Declaration and Virtual Asset Contract Specification.md`](3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md) +4. [`4. Build Artifacts and Deterministic Packing Specification.md`](4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) +5. [`5. Diagnostics, Operations, and Studio Integration Specification.md`](5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) +6. [`6. Versioning, Migration, and Trust Model Specification.md`](6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md) ## Reading Order diff --git a/docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md b/docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md similarity index 100% rename from docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md rename to docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md diff --git a/docs/studio/specs/2. Studio UI Foundations Specification.md b/docs/specs/studio/2. Studio UI Foundations Specification.md similarity index 100% rename from docs/studio/specs/2. Studio UI Foundations Specification.md rename to docs/specs/studio/2. Studio UI Foundations Specification.md diff --git a/docs/studio/specs/3. Studio Components Module Specification.md b/docs/specs/studio/3. Studio Components Module Specification.md similarity index 100% rename from docs/studio/specs/3. Studio Components Module Specification.md rename to docs/specs/studio/3. Studio Components Module Specification.md diff --git a/docs/studio/specs/4. Assets Workspace Specification.md b/docs/specs/studio/4. Assets Workspace Specification.md similarity index 97% rename from docs/studio/specs/4. Assets Workspace Specification.md rename to docs/specs/studio/4. Assets Workspace Specification.md index 48ec204c..f44707a1 100644 --- a/docs/studio/specs/4. Assets Workspace Specification.md +++ b/docs/specs/studio/4. Assets Workspace Specification.md @@ -26,9 +26,9 @@ This specification stabilizes: This specification extends: -- [`1. Studio Shell and Workspace Layout Specification.md`](./1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md) -- [`2. Studio UI Foundations Specification.md`](./2.%20Studio%20UI%20Foundations%20Specification.md) -- [`3. Studio Components Module Specification.md`](./3.%20Studio%20Components%20Module%20Specification.md) +- [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md) +- [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md) +- [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md) For packer-facing semantics, this specification must align with: diff --git a/docs/studio/specs/README.md b/docs/specs/studio/README.md similarity index 76% rename from docs/studio/specs/README.md rename to docs/specs/studio/README.md index ffe92743..82fb58c9 100644 --- a/docs/studio/specs/README.md +++ b/docs/specs/studio/README.md @@ -50,10 +50,10 @@ If a spec edit would require guessing unresolved UI behavior, stop and surface t The current Studio core corpus is: -1. [`1. Studio Shell and Workspace Layout Specification.md`](./1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md) -2. [`2. Studio UI Foundations Specification.md`](./2.%20Studio%20UI%20Foundations%20Specification.md) -3. [`3. Studio Components Module Specification.md`](./3.%20Studio%20Components%20Module%20Specification.md) -4. [`4. Assets Workspace Specification.md`](./4.%20Assets%20Workspace%20Specification.md) +1. [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md) +2. [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md) +3. [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md) +4. [`4. Assets Workspace Specification.md`](4.%20Assets%20Workspace%20Specification.md) ## Reading Order diff --git a/docs/studio/README.md b/docs/studio/README.md deleted file mode 100644 index 604f5e66..00000000 --- a/docs/studio/README.md +++ /dev/null @@ -1,118 +0,0 @@ -# Studio Documentation - -This directory contains the working, planning, normative, and didactic documentation for the `studio` domain. - -`studio` is a standalone domain focused on the UI shell, workspace model, interaction design, and service integration of `prometeu-studio`. - -It follows the same documentary cycle used elsewhere in the repository: - -`agendas -> decisions -> pull-requests -> specs -> learn` - -## Tree - -```text -docs/studio/ -├── agendas/ -├── decisions/ -├── learn/ -├── pull-requests/ -├── specs/ -└── README.md -``` - -## Current Code Context - -The current `prometeu-studio` application already has a lightweight shell: - -- `MainView` composes the application frame; -- `WorkspaceBar` switches between workspaces; -- `EditorWorkspace` is the most concrete workspace today; -- `Assets` is still a placeholder workspace; -- `BuilderWorkspace` exists as an implementation artifact, but Studio UI planning should treat shipping and asset tooling as distinct concerns going forward. - -The first Studio documentation wave should therefore focus on turning the current shell into an intentional UI model instead of adding more placeholders. - -## Responsibilities - -### `agendas/` - -`agendas/` is the staging area for open Studio product and interaction questions. - -Use it to: - -- shape workspace and panel structure, -- compare UI interaction models, -- decide how Studio consumes services and events, -- define what must be visible, staged, or confirmed in the UI. - -When a topic is fully propagated into specs and learn, the corresponding agenda should leave the retained set. - -### `decisions/` - -`decisions/` records closed Studio product and UX decisions before they are fully propagated. - -Use it to: - -- close interaction and architecture choices, -- define invariants for UI behavior, -- capture what must be implemented in Studio code and service contracts. - -Once their content is fully absorbed into specs and learn, they should not be retained just as historical residue. - -### `pull-requests/` - -`pull-requests/` contains execution plans for Studio changes. - -Use it to: - -- break a UI decision into implementation slices, -- separate shell work, workspace work, and service integration work, -- define acceptance criteria and validation paths. - -### `specs/` - -`specs/` contains the normative Studio contract. - -Use it to: - -- define shell structure, -- document workspace responsibilities, -- specify interaction flows, -- stabilize event and service integration expectations. - -### `learn/` - -`learn/` contains didactic Studio material. - -Use it to: - -- explain the mental model of the Studio, -- document why the UI is structured the way it is, -- help future contributors navigate shell, workspaces, and integration boundaries. - -## Recommended Flow - -The preferred Studio documentation flow is: - -1. `agendas/`: open and shape the unresolved UI topic. -2. `decisions/`: close the product or interaction choice. -3. `pull-requests/`: plan propagation into code and specs. -4. `specs/`: integrate the normative Studio contract. -5. `learn/`: consolidate the final model in a didactic form. - -## Practical Rule - -- `agendas/` stores currently open Studio questions. -- `decisions/` stores only decisions that still need propagation. -- `pull-requests/` stores only execution plans for pending work. -- `specs/` stores the normative Studio contract. -- `learn/` stores teaching-oriented Studio knowledge. - -The current Studio core and first `Assets` workspace wave have already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/). -At this moment: - -- `agendas/` retains only topics that are still open; -- `decisions/` is empty because the last accepted wave was fully propagated; -- `pull-requests/` is empty because the historical execution wave was absorbed into `learn/`. - -If implementation exposes a missing UI or interaction decision, stop and return to `agendas/` or `decisions/`. diff --git a/docs/studio/agendas/Palette Management in Studio Agenda.md b/docs/studio/agendas/Palette Management in Studio Agenda.md deleted file mode 100644 index 6e6c0b95..00000000 --- a/docs/studio/agendas/Palette Management in Studio Agenda.md +++ /dev/null @@ -1,165 +0,0 @@ -# Palette Management in Studio Agenda - -Status: Open -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Purpose - -Define how palettes should be presented, identified, edited, and persisted in Studio without blurring the boundary between Studio UX ownership and packer data ownership. - -This agenda is intentionally scoped to the `tile bank` form session. - -It does not define a universal Studio pattern for every asset family that may expose previewable inputs. - -## Problem - -For `tile bank`, each `*.png` file in the asset should be treated as one tile, and each tile brings along a palette extracted during cache construction. - -That extracted palette is part of the bank input model even if the developer did not author a separate palette document by hand. - -In addition, the developer may add more palettes deliberately, up to a maximum of `64` palettes per bank. - -Without a Studio decision for how those palette sources are presented and selected, implementation will guess at least one of the following incorrectly: - -- whether extracted tile palettes are first-class selectable resources or only an implementation detail; -- how the user distinguishes tile-derived palettes, favorite palettes, and asset palettes; -- how the `up to 64 palettes` constraint is enforced and explained in the UI; -- whether default color loading means a palette starts as a full `16`-color color-key-backed candidate set and is then curated by the developer; -- whether Studio writes palette changes directly or routes them through packer. - -## Context - -The current Studio baseline already establishes a few useful constraints: - -- the selected-asset view must expose `Inputs / Preview`, and palettes are explicitly listed as previewable materials in [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md); -- the workspace should help the user inspect real project materials rather than force raw JSON or filesystem inspection; -- Studio should not invent persistence rules locally when packer already owns authoritative asset state and mutation flows. - -The product direction discussed so far is more concrete than a generic palette browser: - -- every `*.png` input of a `tile bank` is one tile; -- each tile yields one extracted palette during cache construction, replacing the older mental model of standalone `file.palette.json` sidecars; -- each bank may integrate at most `64` palettes; -- each palette contains `16` colors and should load with a default color-key baseline; -- the developer should be able to inspect palettes coming from at least three sources: - - palettes extracted from tiles; - - favorite palettes; - - asset palettes; -- from that combined candidate set, the developer chooses which palettes become part of the bank. - -What remains open is not the existence of palette management, but the Studio interaction model around this curation flow. - -The current discussion has also converged on a simpler first-wave UI shape: - -- the left side should use a `transfer list` with custom palette rendering; -- candidate items should show the palette swatch plus stacked source icons when the same palette matches multiple origins; -- the bank selection must stay within `1..64` selected palettes; -- the right side should expose a compact tile-preview panel with: - - a file/tile selector at the top; - - the tile preview in the middle; - - the applied palette strip at the bottom. - -That shape should be treated as `tile bank`-specific. - -Other asset families may need different form sessions and different preview/application models. - -## Current Code Context - -Normative Studio docs already cover shell structure, selected-asset details, and preview expectations, but there is no dedicated Studio decision for palette lifecycle in `tile bank`. - -That means the shell can host palette management, but the product model for palette-source aggregation, curation, and bank admission is still open. - -## Options - -1. Treat extracted tile palettes as implicit data only, and let the bank integrate them automatically without explicit curation. -2. Treat the bank palette set as an asset-scoped curated selection built from multiple palette sources, with Studio orchestrating selection and packer owning persistence. -3. Treat palettes as a fully Studio-owned library/workspace with direct local editing and direct persistence. - -## Tradeoffs - -1. Automatic integration is cheap, but it removes deliberate bank curation, hides the `64`-palette budget, and makes it harder to reason about favorites, reusable palettes, and intentional bank composition. -2. An asset-scoped curated selection aligns with the concrete bank model: the developer sees candidate palettes from tiles, favorites, and asset-level sources, then chooses which ones enter the bank. The tradeoff is that the Studio must explain source, capacity, and duplicate/conflict behavior clearly. -3. A fully Studio-owned palette workspace may look flexible, but it duplicates persistence rules, risks divergence from packer/cache construction, and creates a second authority for bank composition. - -## Recommendation - -Adopt the asset-scoped curated-selection model. - -Studio should treat palette management as a first-class `tile bank` workflow, but not as a new independent persistence authority. - -### Baseline Direction - -- the palette admission surface should belong to the `tile bank` asset workflow; -- Studio should aggregate candidate palettes from tile-derived extraction, favorites, and asset palettes into one curation surface; -- the left side should use a custom-rendered `transfer list` to move palettes into or out of the bank selection; -- the user should explicitly choose which palettes enter the bank, with a fixed `1..64` selected range; -- each candidate palette should expose its source and stable identity clearly enough for inspection and deduplication decisions; -- packer should remain authoritative for extraction, identity, validation, and persistence; -- Studio should own the curation UX, including selection state, tile preview state, capacity feedback, and staged mutation review. - -### First-Wave Scope Recommendation - -The first wave should prioritize a management-oriented bank-composition experience: - -- list tile-derived palettes explicitly in the selected `tile bank` asset details; -- allow inspection of each palette's `16` colors with the default color-key baseline visible; -- aggregate candidate palettes from the supported sources into one transfer-list surface; -- render each palette item with: - - stacked source icons when the same palette matches multiple origins; - - a `16`-swatch horizontal palette strip; -- allow the user to move palettes from the candidate side into the bank `selected` side, with a visible `1..64` constraint; -- expose a compact preview panel on the right side with: - - a tile/file combobox at the top; - - a tile preview surface in the middle; - - a palette strip at the bottom representing the palette currently applied in the preview; -- render the chosen tile preview by applying the currently previewed selected palette to the tile's index matrix; -- defer broad standalone palette-authoring workflows until the bank-composition and persistence contract is closed. - -### Preview-State Baseline - -The first wave should keep preview behavior simple. - -The palette transfer list defines the bank's `selected palettes`. - -The right-side preview panel should always render one of the selected palettes, with the following baseline: - -- when the `selected palettes` set is first created or rebuilt, the first selected palette is used by default in the preview; -- clicking a palette in the `selected` side updates the palette currently shown in the preview; -- changing the previewed palette must not reorder or otherwise mutate the bank selection by itself; -- the preview must always use a palette that belongs to the current `selected palettes` set; -- if the currently previewed palette is removed, the preview falls back to the first remaining selected palette. - -### Why This Direction - -This keeps the Studio honest about its role. - -The Studio should make bank palette composition understandable and operationally safe, but it should not silently become the source of truth for extraction logic or persisted bank data. - -It also keeps the Studio honest about family-specific UX. - -`Tile bank` has a concrete palette-composition workflow tied to tile index matrices and palette admission limits. - -That does not imply that `audio`, `text`, or other asset families should inherit the same transfer-list and active-preview interaction model. - -## Open Questions - -1. How should Studio detect and present duplicate or near-equivalent palettes across tile-derived, favorite, and asset-level sources? -2. Are favorites project-scoped references to existing palettes, or can they diverge into editable copies before bank admission? -3. What is the canonical user-facing identity of a candidate palette in Studio: source bucket plus logical name, file path, extraction origin tile, stable id, or a combination? -4. Should extracted tile palettes always enter the candidate set automatically, or can the developer suppress some of them before curation? -5. Should clicking a palette on the `selected` side be the only interaction needed to change the previewed palette in the first wave? -6. Which palette operations are read-only in the first wave, and which require staged preview/apply treatment? -7. Which parts of this interaction model should remain explicitly `tile bank`-specific, and which parts are reusable Studio form-session primitives? -8. Does the first release need only an asset-scoped `tile bank` section, or also a project-level palette browser for discovery and favorites management? - -## Next Suggested Step - -Turn this agenda into a `decision` that closes four points: - -1. the palette ownership boundary between Studio and packer; -2. the source model for candidate palettes in `tile bank`; -3. the first-wave asset-scoped `transfer list` UX and `1..64` capacity behavior; -4. the right-side preview-panel behavior for tile/file selection, tile rendering, and palette-strip display; -5. the boundary between `tile bank`-specific form-session behavior and reusable Studio primitives; -6. the minimum mutation model for preview, apply, favorites, and cross-asset visibility. diff --git a/docs/studio/agendas/README.md b/docs/studio/agendas/README.md deleted file mode 100644 index 114bbe38..00000000 --- a/docs/studio/agendas/README.md +++ /dev/null @@ -1,50 +0,0 @@ -# Studio Agendas - -This directory contains active Studio discussion agendas. - -Active agendas: - -- [`Palette Management in Studio Agenda.md`](./Palette%20Management%20in%20Studio%20Agenda.md) - -Closed Studio agenda waves must be absorbed into [`../specs/`](../specs/) and [`../learn/`](../learn/) instead of remaining here as historical residue. - -## Purpose - -An agenda exists to drive a decision. - -Use an agenda when: - -- the Studio UI topic is still open, -- multiple interaction models are possible, -- the team still needs tradeoffs and a recommendation, -- implementation would otherwise guess shell or UX behavior. - -## Expected Format - -A Studio agenda should usually include: - -1. Title -2. Status -3. Purpose -4. Domain Owner -5. Current Code Context -6. Options -7. Tradeoffs -8. Recommendation -9. Open Questions -10. Expected Follow-up - -## Writing Rules - -- Keep the document centered on unresolved Studio behavior. -- Anchor the discussion in the actual `prometeu-studio` shell and workspaces. -- Distinguish clearly between shell decisions, workspace decisions, and service-integration decisions. -- Prefer concrete interaction tradeoffs over generic design commentary. - -## Exit Rule - -An agenda should leave the active set when: - -- the main UX tradeoffs are understood, -- a recommendation is ready to adopt, -- and the topic is ready to become a decision record. diff --git a/docs/studio/decisions/README.md b/docs/studio/decisions/README.md deleted file mode 100644 index fca6b44c..00000000 --- a/docs/studio/decisions/README.md +++ /dev/null @@ -1,49 +0,0 @@ -# Studio Decisions - -This directory contains Studio decision records that still need propagation. - -Current retained set: - -- none - -The current Studio decision wave has already been consolidated into: - -- normative specifications under [`../specs/`](../specs/) -- didactic material under [`../learn/`](../learn/) - -## Purpose - -A Studio decision record bridges UI discussion and implementation. - -Use this directory to capture: - -- what Studio behavior was chosen, -- why that interaction model was preferred, -- what constraints now apply to the shell and workspaces, -- what specs, plans, and code paths must be updated. - -## Expected Format - -A Studio decision should usually include: - -1. Title -2. Status -3. Date or Cycle -4. Context -5. Decision -6. Invariants and Constraints -7. Explicit Non-Decisions -8. Propagation Targets -9. Validation Notes or Examples - -## Writing Rules - -- State the adopted Studio behavior early and clearly. -- Keep the tone stable and implementation-oriented. -- Record interaction constraints explicitly. -- Point to exact specs, plans, or UI surfaces that need propagation. - -## Implementation Rule - -If Studio code work reveals a missing decision, do not guess the UX contract. -Return the issue to agenda or decision review. diff --git a/docs/studio/learn/README.md b/docs/studio/learn/README.md deleted file mode 100644 index 2ab940e2..00000000 --- a/docs/studio/learn/README.md +++ /dev/null @@ -1,56 +0,0 @@ -# Studio Learn - -This directory contains didactic Studio knowledge. - -## Purpose - -`learn/` exists to teach the Studio model, not merely to store old discussion output. - -Use it to: - -- explain why the Studio shell is structured the way it is, -- connect UI decisions to practical implementation, -- document common integration pitfalls, -- help future contributors navigate the workspaces and background event model. - -## What Belongs Here - -A Studio `learn` artifact should usually include: - -1. the original UX or architecture problem, -2. the decision that resolved it, -3. the implemented or specified final model, -4. practical examples or flows, -5. common mistakes and warnings, -6. links to relevant specs and plans. - -## Writing Rules - -- Prefer didactic structure over historical accumulation. -- Explain why the Studio model exists, not only what it is. -- Keep terminology aligned with Studio specs. -- Refactor older material when the directory stops feeling like a clear learning path. - -## Refactor Rule - -This directory should be periodically reorganized for better presentation. - -If content grows, prefer: - -- thematic grouping, -- overview documents, -- explicit learning paths, -- consolidation of duplicated explanations. - -## Current Learning Path - -Start here: - -1. [`mental-model-studio-shell.md`](./mental-model-studio-shell.md) -2. [`mental-model-studio-events-and-components.md`](./mental-model-studio-events-and-components.md) -3. [`mental-model-assets-workspace.md`](./mental-model-assets-workspace.md) -4. [`assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md) -5. [`mental-model-asset-mutations.md`](./mental-model-asset-mutations.md) -6. [`bank-composition-editor.md`](./bank-composition-editor.md) -7. [`pack-wizard-shell.md`](./pack-wizard-shell.md) -8. [`project-scoped-state-and-activity.md`](./project-scoped-state-and-activity.md) diff --git a/docs/studio/learn/assets-workspace-execution-wave.md b/docs/studio/learn/assets-workspace-execution-wave.md deleted file mode 100644 index 0734e51f..00000000 --- a/docs/studio/learn/assets-workspace-execution-wave.md +++ /dev/null @@ -1,88 +0,0 @@ -# Assets Workspace Execution Wave - -## Original Problem - -The first `Assets` workspace wave solved many UI problems in small execution slices: - -- workspace foundation; -- asset navigator; -- selected-asset details; -- activity, progress, and logs; -- staged mutations; -- event-driven refactor; -- package and subscription boundaries. - -That historical sequence was useful while implementation was in flight, but it became a poor learning surface. - -## Consolidated Decision - -The stable Studio direction for `Assets` is: - -1. the workspace is asset-first, not file-first; -2. the workspace is event-driven, not refresh-heavy; -3. composition, projection, and rendering are separated; -4. details sections update independently instead of forcing whole-panel rebuilds; -5. mutation review is preview-first; -6. the shell reflects operational lifecycle without taking over workspace-local reasoning. - -## Final Model - -### 1. Workspace Foundation - -- `Assets` is a real workspace, not a placeholder; -- workspace state is explicit about loading, empty, error, and ready conditions; -- selection is stable by asset identity rather than by transient row position. - -### 2. Navigator and Details Split - -- the left side owns navigation and projection; -- the main area teaches the selected asset in a fixed didactic order; -- navigator updates and details updates must not require a workspace-wide redraw by default. - -### 3. Event-Driven Ownership - -- local UI change flows through typed workspace events; -- component-scoped subscriptions replace root-owned redraw logic; -- structural sync and local projection updates stay distinct. - -### 4. Operational Surfaces - -- activity belongs to the shell timeline; -- progress belongs both to the current workspace flow and the broader shell context; -- textual logs are supporting drill-down, not the main explanation surface. - -### 5. Mutation Review - -- preview is the default review surface for sensitive actions; -- blockers, warnings, and safe fixes remain semantically separate; -- modal confirmation is reserved for high-risk commit boundaries. - -## Examples - -### Example: Why the root should not own every redraw - -If one asset row changes because its diagnostics changed, the correct response is a row-scoped update. -Rebuilding navigator, details, and unrelated controls teaches the wrong ownership model and makes the UI harder to reason about. - -### Example: Why the shell still needs activity - -Mutation review happens inside the workspace. -But lifecycle milestones such as `preview ready`, `action applied`, or `action failed` still matter at shell scope because they are part of the user's project timeline. - -## Common Pitfalls and Anti-Patterns - -- Treating `Assets` as a filesystem explorer with extra badges. -- Using `refresh()` as the default answer to local UI state changes. -- Letting details sections depend on a monolithic selected-asset redraw. -- Using logs as the primary explanation surface for mutations. -- Publishing shell activity without keeping workspace-local review visible. - -## References - -- Specs: - - [`../specs/1. Studio Shell and Workspace Layout Specification.md`](../specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md) - - [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) -- Related learn: - - [`./mental-model-assets-workspace.md`](./mental-model-assets-workspace.md) - - [`./mental-model-asset-mutations.md`](./mental-model-asset-mutations.md) - - [`./mental-model-studio-events-and-components.md`](./mental-model-studio-events-and-components.md) diff --git a/docs/studio/learn/bank-composition-editor.md b/docs/studio/learn/bank-composition-editor.md deleted file mode 100644 index ebf2f893..00000000 --- a/docs/studio/learn/bank-composition-editor.md +++ /dev/null @@ -1,126 +0,0 @@ -# Bank Composition Editor - -## Original Problem - -`Bank Composition` needed to become a real editor inside `Asset Details` without collapsing into any of these bad outcomes: - -- direct binding to raw snapshot or manifest shapes; -- overgeneric UI components before the first section existed; -- family-specific rules hidden inside visual controls; -- direct Studio writes to `asset.json`; -- public bus chatter for every local section interaction. - -## Consolidated Decision - -The first-wave `Bank Composition` model is: - -1. Studio owns a DTO projection boundary for the section; -2. the section shell lands early and follows the existing staged-edit rhythm; -3. dual-list and capacity-meter components stay intentionally dumb; -4. one section-scoped coordinator around `StudioFormSession` owns orchestration; -5. public workspace-bus events stay minimal and notification-oriented; -6. `apply` goes through packer and rebinds from refreshed persisted state. - -## Final Model - -### 1. DTO Boundary - -The section never consumes raw packer/runtime structures directly. - -It works with Studio-owned DTOs for: - -- `available` rows from current runtime/details state; -- `selected` rows from persisted composition state. - -Only non-blocking files enter the `available` DTO projection. - -### 2. Section Shell - -`Bank Composition` is a real `Asset Details` section, not a hidden future placeholder. - -The shell follows the existing staged-edit rhythm: - -- `change` -- `apply` -- `reset` -- `cancel` - -Outside edit mode, it teaches the current persisted state in read-only form. - -### 3. Dumb Components - -Two named components exist for this area: - -- `StudioDualListView` -- `StudioAssetCapacityMeter` - -They are intentionally state-driven, not rule-driven. -Family-specific transfer, ordering, and capacity semantics do not live inside these components. - -### 4. Section-Scoped Coordinator - -The main orchestration lives in one section-scoped coordinator built around `StudioFormSession`. - -That coordinator owns: - -- draft lifecycle; -- transfer and reorder effects; -- capacity state; -- blockers and hints; -- apply success and failure handling. - -### 5. WorkspaceBus Boundary - -The public bus surface stays intentionally small. - -First-wave public notifications are about observable state transitions: - -- draft changed; -- capacity changed; -- apply requested; -- apply succeeded; -- apply failed. - -Local edit actions remain local to the section coordinator. - -### 6. Persistence Boundary - -Studio does not write `asset.json` directly for `Bank Composition`. - -The write path is: - -1. Studio submits ordered selected files to packer; -2. packer validates and persists through `asset.json.artifacts`; -3. packer refreshes the minimum runtime/details state; -4. Studio rebinds from refreshed persisted state. - -If apply fails, the draft stays alive and the section remains in editing mode. - -## Examples - -### Example: Why the meter must stay dumb - -Tile banks and sound banks may calculate capacity differently. -That difference belongs in family policies owned by the coordinator, not in `StudioAssetCapacityMeter`. - -### Example: Why `apply` is not a public bus command - -External observers may care that apply was requested or failed. -They do not need to own the local section command sequence for `moveUp`, `moveDown`, `reset`, or `cancel`. - -## Common Pitfalls and Anti-Patterns - -- Binding section UI directly to raw snapshot rows or raw manifest shape. -- Hiding bank-family rules inside `StudioDualListView` or the capacity meter. -- Creating a second staged-edit session model parallel to `StudioFormSession`. -- Turning every local section action into a public workspace-bus event. -- Writing `asset.json` directly from Studio instead of routing through packer. - -## References - -- Specs: - - [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) -- Cross-domain: - - [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) -- Related learn: - - [`./assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md) diff --git a/docs/studio/learn/mental-model-asset-mutations.md b/docs/studio/learn/mental-model-asset-mutations.md deleted file mode 100644 index 15bc82ca..00000000 --- a/docs/studio/learn/mental-model-asset-mutations.md +++ /dev/null @@ -1,128 +0,0 @@ -# Mental Model: Asset Mutations - -## The Problem - -Asset mutations are easy to get wrong in a Studio UI. - -Why? - -Because some actions only update registry state, while others change the physical workspace. - -If the Studio hides that difference, users lose trust quickly. - -## The Rule - -Sensitive asset mutations are `preview-first`. - -That is the most important rule. - -The Studio must not perform destructive or relocational asset changes as if they were harmless button clicks. - -## What The User Must Understand Before Apply - -Before applying a mutation, the user should be able to answer: - -- Which assets are affected? -- Is this touching only the registry, or also the workspace? -- Will something be created, moved, or deleted? -- Are there blockers? -- Are there warnings? -- Is this a safe fix or a risky mutation? - -If the UI cannot answer those questions, the mutation flow is not ready. - -## Why Inline Review Is The Baseline - -The default review surface is an inline staged panel, not a modal. - -That keeps the user anchored in the asset and its surrounding context. - -It lets the user compare: - -- the selected asset, -- the diagnostics, -- the proposed changes, -- and the action consequences - -without bouncing between unrelated windows. - -## Why Modals Still Exist - -Modals are still useful, but only for high-risk final commits. - -Examples: - -- destructive delete; -- major relocation; -- other strongly irreversible actions. - -The mistake would be using modals as a substitute for review. - -Preview is the review. - -Modal confirmation is only the final safety gate when the risk is high enough. - -## The Most Important Distinction - -The Studio must distinguish: - -- registry impact -- workspace impact - -This is one of the most important didactic duties of the asset workspace. - -A user should never have to guess whether a button: - -- merely forgets an asset from management, -- or actually deletes or moves files. - -## Blockers, Warnings, and Safe Fixes - -These categories must stay visually and semantically separate. - -They are not interchangeable kinds of “message”. - -- `blockers` stop the apply path; -- `warnings` tell the user the action is still meaningful but risky or noteworthy; -- `safe fixes` are low-risk corrections and should not be grouped as if they were destructive operations. - -If those three collapse into one list, users stop trusting the flow. - -## Batch Operations - -Batch operations are not just “single asset, repeated many times”. - -They need: - -- an aggregate summary first, -- then drill-down detail. - -Without that, the flow becomes unreadable and users either miss risk or abandon the tool. - -## How Activity Fits In - -The preview itself belongs to the workspace. - -But the shell should still reflect lifecycle milestones such as: - -- preview ready; -- action applied; -- action failed. - -That way the workspace remains the place of review, while the shell keeps the broader operational timeline visible. - -## Common Failure Modes - -Avoid these: - -- destructive apply without preview; -- using raw logs as the main explanation surface; -- mixing safe fixes with deletes; -- showing technical diff data with no user-facing interpretation; -- forcing the user into modal-only flows for ordinary review. - -## Read With - -1. [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) -2. [`mental-model-assets-workspace.md`](./mental-model-assets-workspace.md) -3. [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) diff --git a/docs/studio/learn/mental-model-assets-workspace.md b/docs/studio/learn/mental-model-assets-workspace.md deleted file mode 100644 index 2a6aa920..00000000 --- a/docs/studio/learn/mental-model-assets-workspace.md +++ /dev/null @@ -1,119 +0,0 @@ -# Mental Model: Assets Workspace - -## Why This Workspace Exists - -The `Assets` workspace is not a nicer file browser. - -It exists to make the packer model understandable and usable from the Studio. - -That means the workspace must help a contributor answer questions like: - -- What is the managed asset here? -- Where does it live? -- Which files belong to it? -- What does it produce toward the runtime? -- Is it managed, orphaned, preload-marked, or diagnostically unhealthy? - -If the workspace answered those questions only by showing folders and files, it would teach the wrong mental model. - -## The Core Shift - -The key shift is: - -- not `file-first` -- but `asset-first` - -An asset may contain many files. - -Those files still matter, but they matter as inputs of an asset, not as the primary unit of identity. - -So the workspace is designed to feel like: - -- a structured asset navigator, -- plus a didactic explanation surface for the currently selected asset. - -## Why It Is Still Path-Aware - -`Asset-first` does not mean `filesystem-blind`. - -People still organize projects by directories. - -They still need to know: - -- where the asset root lives; -- which broader folder group it belongs to; -- how to reason about the project layout. - -That is why the workspace remains `path-aware`. - -The important nuance is: - -- path is supporting context -- asset identity is primary - -## What The Left Side Teaches - -The left-side navigator is a custom `Asset Tree` / `Asset Navigator`. - -It teaches the model visually: - -- groups may reflect location or parent folders, -- asset nodes are the real unit of navigation, -- icons and badges tell the story quickly, -- orphan and managed assets can coexist without becoming ambiguous. - -This is better than a raw file tree because the user learns the packer model by looking at the navigation itself. - -## What The Main Area Teaches - -The selected asset view is intentionally structured in a fixed order: - -1. `Summary` -2. `Runtime Contract` -3. `Inputs / Preview` -4. `Diagnostics` -5. `Actions` - -That order matters. - -It starts by explaining what the asset is, then what it produces, then what it contains, then what is wrong, and finally what the user can do. - -That is a teaching sequence, not just a layout sequence. - -## Why Preview Matters - -Preview is not decorative. - -Preview is part of how the workspace bridges the conceptual asset model with the real materials inside the project. - -Examples: - -- an image bank should let the user inspect images and palettes; -- an audio asset should let the user inspect sound inputs; -- text-like artifacts should be inspectable as text when that helps understanding. - -This makes the workspace feel grounded in real project materials while still preserving an asset-first model. - -## What To Avoid - -Common mistakes: - -- turning the workspace into a raw filesystem explorer with extra badges; -- making path the true identity instead of the asset; -- showing only diagnostics and forgetting the actual asset model; -- treating orphan as if it meant broken; -- hiding runtime-facing information behind technical dumps. - -## Practical Read Order - -Read these together: - -1. [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) -2. [`mental-model-asset-mutations.md`](./mental-model-asset-mutations.md) -3. [`../../packer/learn/mental-model-packer.md`](../../packer/learn/mental-model-packer.md) - -That path explains: - -- what the packer believes, -- how the Studio presents it, -- and how the user should reason about asset operations. diff --git a/docs/studio/learn/mental-model-studio-events-and-components.md b/docs/studio/learn/mental-model-studio-events-and-components.md deleted file mode 100644 index 95837a26..00000000 --- a/docs/studio/learn/mental-model-studio-events-and-components.md +++ /dev/null @@ -1,76 +0,0 @@ -# Studio Events and Components Mental Model - -Two things are meant to stop the Studio from becoming messy as it grows: - -- a typed event model; -- a single authoritative control layer. - -These two rules solve different problems, but they reinforce each other. - -## Why a Studio-owned event system? - -Without it, the shell, workspaces, and services begin to call each other directly. - -That usually feels fine at first, because the UI is small. Then the application gains: - -- global activity surfaces; -- background operations; -- multiple workspaces; -- status and progress reporting; -- cross-cutting actions such as run or diagnostics. - -At that point, direct references become the path of least resistance and the UI starts coupling itself in ways that are hard to unwind. - -The Studio event system exists to keep event publication explicit and typed. - -## Why both a global bus and workspace buses? - -Because the Studio needs both segregation and shared visibility. - -Workspaces should be able to keep their local activity scoped. -The shell should still be able to observe what is happening globally. - -The chosen rule is therefore: - -- each workspace has its own bus; -- the Studio has a global bus; -- every workspace event is automatically republished to the global bus. - -This means callers do not need to decide when to duplicate publication manually. - -## Why not rely on raw JavaFX controls directly? - -Because raw JavaFX use spreads quickly and creates UI drift. - -When each part of the app consumes JavaFX controls directly, the Studio gradually accumulates: - -- inconsistent naming; -- inconsistent styling hooks; -- repeated local wrappers; -- uneven behavior between screens; -- more work each time theme or locale behavior needs to change. - -That is why the Studio uses `prometeu-studio-components` as its visual control layer. - -## Does that mean reimplementing JavaFX? - -No. - -The goal is not to reproduce every JavaFX API. -The goal is to expose the Studio-facing API the application actually needs. - -That keeps the control layer: - -- opinionated; -- smaller than JavaFX; -- aligned with the Studio's own UI dialect. - -## Practical reading rule - -When adding UI code, ask two questions: - -1. Is this communication really an event? -2. Is this control part of the Studio's visible dialect? - -If the answer to the first question is yes, it should probably publish a typed Studio event. -If the answer to the second question is yes, it should probably come through `prometeu-studio-components`. diff --git a/docs/studio/learn/mental-model-studio-shell.md b/docs/studio/learn/mental-model-studio-shell.md deleted file mode 100644 index 785e44b4..00000000 --- a/docs/studio/learn/mental-model-studio-shell.md +++ /dev/null @@ -1,60 +0,0 @@ -# Studio Shell Mental Model - -The Studio shell exists to frame workspaces, not to absorb every piece of UI. - -That distinction matters because a lot of early JavaFX applications slowly become a single giant layout where every new concern gets added to the same frame. The shell model chosen here avoids that. - -## What belongs to the shell? - -The shell owns: - -- project entry through a launcher or home surface; -- global menus; -- fixed workspace navigation; -- the workspace host; -- the right-side utility surface; -- the always-visible run surface. - -The shell does not own the full operating detail of every domain workflow. - -## What belongs to a workspace? - -A workspace owns its main body and its domain-specific detail. - -That includes things like: - -- editor-specific structure; -- asset-management views; -- debugger and profiler views; -- workspace-local logs and detailed operational output. - -This is why the Studio does not define a mandatory single global console as the primary logging model. - -## Why avoid a fully docked shell right now? - -Because the Studio is still proving its topology. - -If docking is introduced too early, the codebase starts solving these problems before the product actually needs them: - -- panel restore rules; -- drag-and-drop docking behavior; -- focus and lifecycle complexity; -- layout persistence; -- too many shell-level extension points. - -The structured shell keeps the frame stable without pretending the full IDE model is already known. - -## Why is `Run` always visible? - -Because run is a primary action, not a secondary panel. - -If running the project requires opening a tab first, the shell is hiding one of the most important actions behind navigation friction. The Studio therefore treats `Run` as a persistent shell control. - -## Practical reading rule - -When deciding whether something belongs in the shell or in a workspace, ask: - -> “Is this a Studio-wide framing concern, or is it operational detail of one workspace?” - -If it is framing, it belongs in the shell. -If it is operational detail, it probably belongs in the workspace. diff --git a/docs/studio/learn/pack-wizard-shell.md b/docs/studio/learn/pack-wizard-shell.md deleted file mode 100644 index 200a74ae..00000000 --- a/docs/studio/learn/pack-wizard-shell.md +++ /dev/null @@ -1,87 +0,0 @@ -# Pack Wizard Shell - -## Original Problem - -The `Assets` workspace already had a reserved `Pack` action, but that did not answer the real product question: - -How should Studio behave when the developer wants to pack the current build set? - -The risk was building a visually plausible modal that quietly reimplemented packer semantics or hid the real operational phases. - -## Consolidated Decision - -The stable first-wave rule is: - -`Pack` is a Studio-owned wizard shell over packer-owned operations. - -The wizard is phase-based: - -1. `Summary` -2. `Validation` -3. `Packing` -4. `Result` - -Studio owns presentation and state binding. -Packer owns summary, validation, execution, progress, and result semantics. - -## Final Model - -### 1. Workspace-Level Entry Point - -- `Pack` is a workspace action, not a selected-asset action; -- the user is operating on the current pack set, not on one asset in isolation. - -### 2. Summary - -- the wizard asks packer for the current build-set summary; -- Studio does not count navigator rows and pretend that is the build set; -- the canonical runtime artifact is explicitly `assets.pa`. - -### 3. Validation - -- validation runs only on `registered + included in build`; -- blocking diagnostics stop the flow before execution; -- warnings may be visible, but they do not become blockers unless packer classifies them that way. - -### 4. Packing - -- execution is operational and non-editable; -- progress comes from packer-owned progress state or events; -- the UI does not simulate progress with timers; -- the first wave is non-cancelable. - -### 5. Result - -- the primary summary shows final status, packed asset count, elapsed time, and `assets.pa`; -- companion artifacts are supporting detail, not the headline of the result screen; -- the UI must distinguish blocked, failed, and successful outcomes. - -## Examples - -### Example: Why validation is a separate phase - -If the wizard jumps straight from summary into execution, the user loses the explicit gate that explains why packing is blocked. -Validation exists to make the gate understandable before byte emission begins. - -### Example: Why Studio must not fake progress - -A fake progress bar may look smoother, but it lies about operational ownership. -If the packer is the owner of execution semantics, the UI must reflect packer-owned progress honestly. - -## Common Pitfalls and Anti-Patterns - -- Treating pack summary as a local Studio recomputation. -- Using one opaque modal state instead of explicit operational phases. -- Letting unrelated assets influence wizard validation. -- Exposing fake cancel behavior that the packer does not actually support. -- Making companion artifacts dominate the main result summary. - -## References - -- Specs: - - [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) -- Cross-domain: - - [`../../packer/learn/pack-wizard-summary-validation-and-pack-execution.md`](../../packer/learn/pack-wizard-summary-validation-and-pack-execution.md) - - [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) -- Related learn: - - [`./assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md) diff --git a/docs/studio/learn/project-scoped-state-and-activity.md b/docs/studio/learn/project-scoped-state-and-activity.md deleted file mode 100644 index 2e61aeb6..00000000 --- a/docs/studio/learn/project-scoped-state-and-activity.md +++ /dev/null @@ -1,57 +0,0 @@ -# Project-Scoped State and Activity - -## Original Problem - -Some Studio state is global by nature, but some state is clearly tied to one opened project. - -If project-local state is stored as if it were application-global, the shell starts mixing unrelated histories and the project root stops being the obvious home of Studio-owned project data. - -## Consolidated Decision - -The stable direction is: - -1. project-local Studio state lives under `.studio/` inside the project root; -2. shell activity is restored and persisted per project; -3. persisted activity history is bounded; -4. `.studio/` is the reserved root for future project-local Studio settings. - -## Final Model - -### 1. Storage Root - -- each project owns `.studio/`; -- new-project scaffolding creates that directory; -- `.workspace/` is not the project-local Studio root for this model. - -### 2. Activity Persistence - -- shell activity is loaded when the project opens; -- new activity is appended to that project's local history; -- history is trimmed to the latest `500` entries. - -### 3. Scope Rule - -- project-local shell history belongs to the project; -- launcher-global concerns remain outside this storage path; -- future Studio project configuration can live under the same `.studio/` root. - -## Examples - -### Example: Why activity cannot stay application-global - -If two projects have one shared persisted feed, the shell stops teaching the user what happened in the currently opened project. -That destroys causality instead of preserving it. - -## Common Pitfalls and Anti-Patterns - -- Treating project activity as if it were launcher-global state. -- Mixing unrelated projects into one persisted activity history. -- Leaving project-local Studio files in ad hoc roots instead of `.studio/`. -- Letting unbounded activity persistence grow without a hard cap. - -## References - -- Specs: - - [`../specs/1. Studio Shell and Workspace Layout Specification.md`](../specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md) -- Related learn: - - [`./mental-model-studio-shell.md`](./mental-model-studio-shell.md) diff --git a/docs/studio/pull-requests/README.md b/docs/studio/pull-requests/README.md deleted file mode 100644 index 7d726806..00000000 --- a/docs/studio/pull-requests/README.md +++ /dev/null @@ -1,46 +0,0 @@ -# Studio Pull Requests - -This directory contains executable plans for Studio work. - -Current retained set: - -- none - -The previous Studio execution wave has already been consolidated into [`../learn/`](../learn/) and propagated into [`../specs/`](../specs/). - -## Purpose - -A Studio pull-request or plan artifact packages a decision into an implementable sequence. - -Use it to: - -- separate shell work from workspace work, -- describe service and event-lane integration steps, -- define acceptance criteria for UI behavior, -- make validation and regression risks explicit before code changes. - -## Expected Format - -A Studio plan should usually include: - -1. Briefing -2. Objective -3. Dependencies -4. Scope -5. Non-Goals -6. Execution Method -7. Acceptance Criteria -8. Validation -9. Affected Artifacts - -## Writing Rules - -- Organize by execution sequence, not by brainstorming. -- Keep visual design, interaction behavior, and service integration clearly separated. -- State what the user should be able to do after the change lands. -- Tie the plan back to Studio specs and decisions explicitly. - -## Current Queue - -When a new Studio execution wave starts, add only the plans that still represent pending work. -Do not repopulate this directory with already-absorbed historical implementation slices.