diff --git a/crates/host/prometeu-host-desktop-winit/src/overlay.rs b/crates/host/prometeu-host-desktop-winit/src/overlay.rs index b6725909..f1d707a1 100644 --- a/crates/host/prometeu-host-desktop-winit/src/overlay.rs +++ b/crates/host/prometeu-host-desktop-winit/src/overlay.rs @@ -2,7 +2,7 @@ use crate::stats::HostStats; use prometeu_firmware::Firmware; const PANEL_X: usize = 6; -const PANEL_Y: usize = 10; +const PANEL_Y: usize = 3; const PANEL_WIDTH: usize = 170; const PANEL_PADDING_X: usize = 8; const PANEL_PADDING_Y: usize = 3; diff --git a/discussion/.backups/index.ndjson.20260410-192035.bak b/discussion/.backups/index.ndjson.20260410-192035.bak new file mode 100644 index 00000000..0e13da96 --- /dev/null +++ b/discussion/.backups/index.ndjson.20260410-192035.bak @@ -0,0 +1,25 @@ +{"type":"meta","next_id":{"DSC":25,"AGD":25,"DEC":13,"PLN":11,"LSN":29,"CLSN":1}} +{"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["perf","runtime","telemetry"],"agendas":[{"id":"AGD-0021","file":"workflow/agendas/AGD-0021-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0008","file":"workflow/decisions/DEC-0008-full-migration-to-atomic-telemetry.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0007","file":"workflow/plans/PLN-0007-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0028","file":"lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} +{"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"workflow/decisions/DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"workflow/plans/PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]} +{"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]} +{"type":"discussion","id":"DSC-0022","status":"done","ticket":"tile-bank-vs-glyph-bank-domain-naming","title":"Glyph Bank Domain Naming Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["gfx","runtime","naming","domain-model"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} +{"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} +{"type":"discussion","id":"DSC-0002","status":"open","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0001","file":"workflow/agendas/AGD-0001-runtime-edge-test-plan.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"workflow/agendas/AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0004","status":"open","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0003","file":"workflow/agendas/AGD-0003-system-run-cart.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"workflow/agendas/AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"workflow/agendas/AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0008","status":"done","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[{"id":"AGD-0007","file":"workflow/agendas/AGD-0007-perf-runtime-telemetry-hot-path.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0005","file":"workflow/decisions/DEC-0005-perf-push-based-telemetry-model.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0005","file":"workflow/plans/PLN-0005-perf-push-based-telemetry-implementation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0026","file":"lessons/DSC-0008-perf-runtime-telemetry-hot-path/LSN-0026-push-based-telemetry-model.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} +{"type":"discussion","id":"DSC-0009","status":"open","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0008","file":"workflow/agendas/AGD-0008-perf-async-background-work-lanes-for-assets-and-fs.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0010","status":"open","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0009","file":"workflow/agendas/AGD-0009-perf-host-desktop-frame-pacing-and-presentation.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0011","status":"open","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0010","file":"workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0012","status":"open","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0013","status":"open","ticket":"perf-host-debug-overlay-isolation","title":"Agenda - [PERF] Host Debug Overlay Isolation","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[{"id":"AGD-0012","file":"workflow/agendas/AGD-0012-perf-host-debug-overlay-isolation.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-10"},{"id":"AGD-0022","file":"AGD-0022-host-overlay-tooling-boundary-revision.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"},{"id":"AGD-0023","file":"AGD-0023-overlay-log-metric-last-frame.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0007","file":"workflow/decisions/DEC-0007-perf-host-debug-overlay-isolation.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"},{"id":"DEC-0009","file":"DEC-0009-host-overlay-tooling-boundary.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0022"},{"id":"DEC-0010","file":"DEC-0010-overlay-log-metric-last-frame.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0023"}],"plans":[{"id":"PLN-0006","file":"workflow/plans/PLN-0006-perf-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"},{"id":"PLN-0008","file":"PLN-0008-host-overlay-native-composition-alignment.md","status":"in_progress","created_at":"2026-04-10","updated_at":"2026-04-10","ref_decisions":["DEC-0007","DEC-0008","DEC-0009","DEC-0010"]}],"lessons":[{"id":"LSN-0027","file":"lessons/DSC-0013-perf-host-debug-overlay-isolation/LSN-0027-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} +{"type":"discussion","id":"DSC-0024","status":"open","ticket":"generic-memory-bank-slot-contract","title":"Agenda - Generic Memory Bank Slot Contract","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["runtime","asset","memory-bank","slots","host"],"agendas":[{"id":"AGD-0024","file":"AGD-0024-generic-memory-bank-slot-contract.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0012","file":"DEC-0012-asset-manager-bank-telemetry-slot-contract.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0024"}],"plans":[{"id":"PLN-0010","file":"PLN-0010-asset-manager-bank-telemetry-slot-contract.md","status":"in_progress","created_at":"2026-04-10","updated_at":"2026-04-10","ref_decisions":["DEC-0012"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0014","status":"open","ticket":"perf-vm-allocation-and-copy-pressure","title":"Agenda - [PERF] VM Allocation and Copy Pressure","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0013","file":"workflow/agendas/AGD-0013-perf-vm-allocation-and-copy-pressure.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0015","status":"open","ticket":"perf-cartridge-boot-and-program-ownership","title":"Agenda - [PERF] Cartridge Boot and Program Ownership","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0014","file":"workflow/agendas/AGD-0014-perf-cartridge-boot-and-program-ownership.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0016","status":"done","ticket":"tilemap-empty-cell-vs-tile-id-zero","title":"Tilemap Empty Cell vs Tile ID Zero","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0015","file":"workflow/agendas/AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"lessons/DSC-0016-tilemap-empty-cell-semantics/LSN-0022-tilemap-empty-cell-convergence.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]} +{"type":"discussion","id":"DSC-0017","status":"done","ticket":"asset-entry-metadata-normalization-contract","title":"Asset Entry Metadata Normalization Contract","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0016","file":"workflow/agendas/AGD-0016-asset-entry-metadata-normalization-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[{"id":"DEC-0004","file":"workflow/decisions/DEC-0004-asset-entry-metadata-normalization-contract.md","status":"accepted","created_at":"2026-04-09","updated_at":"2026-04-09"}],"plans":[],"lessons":[{"id":"LSN-0023","file":"lessons/DSC-0017-asset-metadata-normalization/LSN-0023-typed-asset-metadata-helpers.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]} +{"type":"discussion","id":"DSC-0018","status":"done","ticket":"asset-load-asset-id-int-contract","title":"Asset Load Asset ID Int Contract","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["asset","runtime","abi"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0019","file":"lessons/DSC-0018-asset-load-asset-id-int-contract/LSN-0019-asset-load-id-abi-convergence.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} +{"type":"discussion","id":"DSC-0019","status":"done","ticket":"jenkinsfile-correction","title":"Jenkinsfile Correction and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins"],"agendas":[{"id":"AGD-0017","file":"workflow/agendas/AGD-0017-jenkinsfile-correction.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0002","file":"workflow/decisions/DEC-0002-jenkinsfile-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0002","file":"workflow/plans/PLN-0002-jenkinsfile-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0020","file":"lessons/DSC-0019-jenkins-ci-standardization/LSN-0020-jenkins-standard-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]} diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 0e13da96..a6ed74ff 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,4 +1,4 @@ -{"type":"meta","next_id":{"DSC":25,"AGD":25,"DEC":13,"PLN":11,"LSN":29,"CLSN":1}} +{"type":"meta","next_id":{"DSC":25,"AGD":25,"DEC":13,"PLN":11,"LSN":30,"CLSN":1}} {"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["perf","runtime","telemetry"],"agendas":[{"id":"AGD-0021","file":"workflow/agendas/AGD-0021-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0008","file":"workflow/decisions/DEC-0008-full-migration-to-atomic-telemetry.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0007","file":"workflow/plans/PLN-0007-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0028","file":"lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} {"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"workflow/decisions/DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"workflow/plans/PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]} {"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]} @@ -16,7 +16,7 @@ {"type":"discussion","id":"DSC-0011","status":"open","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0010","file":"workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0012","status":"open","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0013","status":"open","ticket":"perf-host-debug-overlay-isolation","title":"Agenda - [PERF] Host Debug Overlay Isolation","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[{"id":"AGD-0012","file":"workflow/agendas/AGD-0012-perf-host-debug-overlay-isolation.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-10"},{"id":"AGD-0022","file":"AGD-0022-host-overlay-tooling-boundary-revision.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"},{"id":"AGD-0023","file":"AGD-0023-overlay-log-metric-last-frame.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0007","file":"workflow/decisions/DEC-0007-perf-host-debug-overlay-isolation.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"},{"id":"DEC-0009","file":"DEC-0009-host-overlay-tooling-boundary.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0022"},{"id":"DEC-0010","file":"DEC-0010-overlay-log-metric-last-frame.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0023"}],"plans":[{"id":"PLN-0006","file":"workflow/plans/PLN-0006-perf-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"},{"id":"PLN-0008","file":"PLN-0008-host-overlay-native-composition-alignment.md","status":"in_progress","created_at":"2026-04-10","updated_at":"2026-04-10","ref_decisions":["DEC-0007","DEC-0008","DEC-0009","DEC-0010"]}],"lessons":[{"id":"LSN-0027","file":"lessons/DSC-0013-perf-host-debug-overlay-isolation/LSN-0027-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} -{"type":"discussion","id":"DSC-0024","status":"open","ticket":"generic-memory-bank-slot-contract","title":"Agenda - Generic Memory Bank Slot Contract","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["runtime","asset","memory-bank","slots","host"],"agendas":[{"id":"AGD-0024","file":"AGD-0024-generic-memory-bank-slot-contract.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0012","file":"DEC-0012-asset-manager-bank-telemetry-slot-contract.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0024"}],"plans":[{"id":"PLN-0010","file":"PLN-0010-asset-manager-bank-telemetry-slot-contract.md","status":"in_progress","created_at":"2026-04-10","updated_at":"2026-04-10","ref_decisions":["DEC-0012"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0024","status":"done","ticket":"generic-memory-bank-slot-contract","title":"Agenda - Generic Memory Bank Slot Contract","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["runtime","asset","memory-bank","slots","host"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"lessons/DSC-0024-generic-memory-bank-slot-contract/LSN-0029-slot-first-bank-telemetry-belongs-in-asset-manager.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} {"type":"discussion","id":"DSC-0014","status":"open","ticket":"perf-vm-allocation-and-copy-pressure","title":"Agenda - [PERF] VM Allocation and Copy Pressure","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0013","file":"workflow/agendas/AGD-0013-perf-vm-allocation-and-copy-pressure.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0015","status":"open","ticket":"perf-cartridge-boot-and-program-ownership","title":"Agenda - [PERF] Cartridge Boot and Program Ownership","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0014","file":"workflow/agendas/AGD-0014-perf-cartridge-boot-and-program-ownership.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0016","status":"done","ticket":"tilemap-empty-cell-vs-tile-id-zero","title":"Tilemap Empty Cell vs Tile ID Zero","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0015","file":"workflow/agendas/AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"lessons/DSC-0016-tilemap-empty-cell-semantics/LSN-0022-tilemap-empty-cell-convergence.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]} diff --git a/discussion/lessons/DSC-0024-generic-memory-bank-slot-contract/LSN-0029-slot-first-bank-telemetry-belongs-in-asset-manager.md b/discussion/lessons/DSC-0024-generic-memory-bank-slot-contract/LSN-0029-slot-first-bank-telemetry-belongs-in-asset-manager.md new file mode 100644 index 00000000..41ac47c7 --- /dev/null +++ b/discussion/lessons/DSC-0024-generic-memory-bank-slot-contract/LSN-0029-slot-first-bank-telemetry-belongs-in-asset-manager.md @@ -0,0 +1,70 @@ +--- +id: LSN-0029 +ticket: generic-memory-bank-slot-contract +title: Slot-First Bank Telemetry Belongs in AssetManager +created: 2026-04-10 +tags: [runtime, asset, telemetry, memory-bank, slots] +--- + +## Context + +This discussion started from a mismatch between how memory banks were modeled and how engineers actually reason about them in the runtime. The public-facing bank path still leaned on byte totals and helper structures such as `BankStats`, even though the actual operational model was slot occupancy for `GLYPH` and `SOUNDS`. + +The refactor closed that gap by making the visible bank summary slot-first and moving the canonical summary ownership to `AssetManager`. + +## Key Decisions + +### AssetManager Owns the Visible Bank Summary + +**What:** +The canonical visible bank telemetry is exposed by `AssetManager`, not by `MemoryBanks`, and uses `BankTelemetry { bank_type, used_slots, total_slots }`. + +**Why:** +`AssetManager` is the domain owner that already knows loaded assets, active slot occupancy, and the bank summary that host tooling and certification need. Keeping the visible summary there prevents the abstraction from drifting into a generic but less useful lower-level surface. + +**Trade-offs:** +This keeps the visible contract simpler and more explicit, but it also means low-level byte accounting and residency details cannot be treated as the primary public model anymore. + +### Slot Occupancy Is the Operational Truth + +**What:** +The public bank summary is slot-first. Detailed inspection remains per-slot through slot references and slot enums. + +**Why:** +Banks are operated, debugged, and visualized in terms of occupied slots, not aggregate bytes. Overlay and certification become easier to understand when they read the same unit the runtime actually uses to allocate and inspect banks. + +**Trade-offs:** +Byte totals may still exist internally for implementation needs, but they no longer define the public contract. Any internal byte path must stay subordinate to the slot model. + +### Certification Must Share the Same Unit as Inspection + +**What:** +Certification moved from `max_gfx_bytes` / `max_audio_bytes` to slot-based ceilings such as `max_glyph_slots_used` and `max_sound_slots_used`. + +**Why:** +A certification rule should use the same visible semantics as overlay and diagnostics. If inspection is slot-first but certification is byte-first, engineers end up debugging two different models for the same bank state. + +**Trade-offs:** +The migration removes some old byte-oriented limits, so any future need for byte budgeting must be introduced as a separate internal concern instead of piggybacking on the visible bank contract. + +## Patterns and Algorithms + +- Put the canonical telemetry contract at the domain owner that already knows the operational state, instead of at a lower abstraction that would need extra interpretation. +- Prefer the unit engineers actually use in debugging and operations for the public contract. +- Keep detailed inspection and summary telemetry separate: + summary telemetry answers "how full is each bank?"; + slot inspection answers "what is in this slot?". +- When a public telemetry model changes units, migrate certification and debugger payloads in the same change set. + +## Pitfalls + +- Leaving byte-oriented helper types in the visible path keeps old semantics alive even after the new summary exists. +- Moving the generic contract too low in the stack can create an abstract API that is technically reusable but no longer aligned with the runtime's operational owner. +- Updating overlay without updating certification creates inconsistent diagnostics. +- Renaming presentation labels without aligning canonical bank names causes drift between `BankType`, telemetry payloads, and docs. + +## Takeaways + +- Public bank telemetry should reflect slot occupancy, not leftover byte-accounting structures. +- `AssetManager` is the right place for the canonical visible bank summary because it owns the practical bank state. +- Overlay, debugger, syscalls, and certification should all consume the same bank unit to avoid semantic drift. diff --git a/discussion/workflow/agendas/AGD-0024-generic-memory-bank-slot-contract.md b/discussion/workflow/agendas/AGD-0024-generic-memory-bank-slot-contract.md deleted file mode 100644 index 6dc203cb..00000000 --- a/discussion/workflow/agendas/AGD-0024-generic-memory-bank-slot-contract.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -id: AGD-0024 -ticket: generic-memory-bank-slot-contract -title: Agenda - Generic Memory Bank Slot Contract -status: accepted -created: 2026-04-10 -resolved: 2026-04-10 -decision: DEC-0012 -tags: [runtime, asset, memory-bank, slots, host] ---- - -# Agenda - Generic Memory Bank Slot Contract - -## Contexto - -Hoje o runtime e o host expõem bancos de memória principalmente pela ótica de bytes totais/usados, enquanto a organização real do hardware já é fortemente orientada a slots. No estado atual: - -- `GFX` e `AUD` aparecem como casos especiais espalhados entre `AssetManager`, `MemoryBanks`, `AssetBridge`, telemetria e overlay; -- os pools concretos são específicos (`glyph_bank_pool`, `sound_bank_pool`); -- a visualização do overlay precisou reinterpretar um modelo em bytes para algo que, operacionalmente, é mais bem entendido como ocupação de slots. - -O pedido do usuário é explicitamente mudar essa ênfase: manter bytes como detalhe secundário quando necessário, mas estruturar o modelo principal como **memory banks by slots**, com possibilidade de contrato específico no domínio de `MemoryBanks` para gerir esses valores. - -Na continuação da discussão, o usuário endureceu a direção: - -- `BankPolicy` deve ser removido por completo; -- `BankStats` deve ser removido por completo; -- o contrato exposto deve trabalhar somente com ocupação por slots, por exemplo: - - `glyph_slots_occupied / glyph_slots.len()` - - `sound_slots_occupied / sound_slots.len()` - -## Problema - -O modelo atual mistura dois níveis de abstração: - -1. **Contrato de capacidade em bytes**, útil para certificação e budgets; -2. **Contrato operacional por slots**, que é o que o host e o programador realmente percebem ao lidar com banks. - -Isso gera acoplamento e duplicação: - -- o domínio conhece `GFX` e `AUD` como exceções, em vez de bancos genéricos com propriedades próprias; -- `BankStats` privilegia bytes e trata slots como apêndice; -- `MemoryBanks` não oferece um contrato consolidado para estatísticas e ocupação por slots; -- o overlay precisa montar sua própria leitura mais útil em cima de um modelo que não foi desenhado para isso. - -Com a direção nova do usuário, há um problema adicional: não basta rebaixar bytes a papel secundário no contrato exposto. As estruturas atuais que orbitam essa semântica (`BankPolicy` e `BankStats`) passam a ser vistas como parte do problema e não como base aceitável para a solução. - -## Pontos Criticos - -- **Fato:** O hardware já é organizado por slots para glyph e sound banks. -- **Fato:** O overlay quer mostrar ocupação por slots, não capacidade em bytes. -- **Fato:** O usuário quer que o contrato exposto use apenas `used_slots` e `total_slots`. -- **Fato:** `BankPolicy` e `BankStats` não devem permanecer como contrato nem como modelagem principal deste domínio. -- **Risco:** Remover essas estruturas sem separar claramente contrato exposto e necessidades internas pode quebrar telemetria e certificação existentes. -- **Risco:** Se bytes continuarem aparecendo no contrato público, a refatoração perde seu objetivo. -- **Tradeoff:** Um contrato mínimo de slots simplifica host/overlay e o domínio exposto, mas exige reposicionar qualquer necessidade residual baseada em bytes. - -## Opcoes - -- **Opção A (Recomendada):** Introduzir um contrato genérico de memory bank orientado exclusivamente a slots no contrato exposto. - - `MemoryBanks` passa a oferecer um contrato explícito para: - - quantidade de slots; - - slots ocupados; - - consulta de slots; - - enumeração genérica de banks. - - `GLYPH` e `SOUND` tornam-se instâncias desse modelo. - - `BankPolicy` e `BankStats` deixam de existir como superfícies do contrato. - -- **Opção B:** Manter `BankPolicy` e `BankStats` internamente, escondendo-os só no host. - - Menor custo imediato. - - Não atende a direção explícita da discussão atual. - -- **Opção C:** Preservar um contrato híbrido com slots e bytes lado a lado. - - Dá continuidade incremental. - - Mantém exatamente a ambiguidade que o usuário quer remover. - -## Sugestao / Recomendacao - -Seguir com a **Opção A**, com os seguintes princípios: - -1. O domínio de memory banks deve ser **slot-first**. -2. O contrato exposto deve usar somente `used_slots` e `total_slots`. -3. `BankPolicy` e `BankStats` devem ser removidos por completo. -4. `MemoryBanks` deve possuir um contrato específico e explícito para ocupação por slots. -5. O host overlay deve consumir esse modelo genérico sem saber detalhes especiais de `GLYPH` vs `SOUNDS`, além de rótulo e contagem. -6. A revisão deve evitar abstração vazia: o contrato genérico precisa mapear diretamente para `GlyphBank` e `SoundBank`. - -Nomenclatura canônica acordada para a camada genérica: - -- `GLYPH` -- `SOUNDS` - -`GFX` e `AUD` não devem ser usados como nomes canônicos do contrato genérico de banks, pois são apelidos de apresentação e não os nomes corretos do domínio. - -## Perguntas em Aberto - -- Nenhuma resposta final ainda sobre a forma exata do artefato, mas em 2026-04-10 o usuário fechou os seguintes direcionadores: - - a telemetria necessária deve ser gerenciada pelo `AssetManager`, adicionando os banks ao payload; - - a telemetria deve carregar somente o enum do tipo do bank, não uma abstração genérica adicional no contrato; - - o detalhamento operacional deve ocorrer por enum de slot; - - exemplos concretos do formato esperado ainda precisam ser avaliados antes de encerrar a agenda. - -### Respostas consolidadas desta rodada - -1. **Origem da telemetria:** não mover a genericidade principal para `MemoryBanks`; o `AssetManager` deve gerenciar e expor a telemetria necessária dos banks. -2. **Forma da telemetria:** a telemetria exposta deve carregar somente o enum do tipo do bank. -3. **Detalhamento dos slots:** a leitura operacional deve ser feita por enum de slot. -4. **Formato preferido:** seguir com um resumo por bank no formato do exemplo 1 (`bank_type`, `used_slots`, `total_slots`). -5. **Bytes fake:** bytes não devem continuar no contrato novo de telemetria dos banks. -6. **Certificação:** as regras `max_gfx_bytes` e `max_audio_bytes` devem sair e ser substituídas por limites de slots para `GLYPH` e `SOUND`. -7. **Origem do contrato visível:** o `AssetManager` deve expor diretamente esse resumo por bank. - -Exemplo alvo discutido: - -```rust -pub struct BankTelemetry { - pub bank_type: BankType, - pub used_slots: usize, - pub total_slots: usize, -} -``` - -Origem esperada: - -```rust -impl AssetManager { - pub fn bank_telemetry(&self) -> Vec { ... } -} -``` - -Impacto já identificado para certificação: - -- remover `max_gfx_bytes` -- remover `max_audio_bytes` -- substituir por algo como: - - `max_glyph_slots_used` - - `max_sound_slots_used` - -## Criterio para Encerrar - -Esta agenda pode ser encerrada quando houver direção fechada sobre: - -- contrato genérico por slots; -- remoção completa de `BankPolicy` e `BankStats`; -- ponto de residência da abstração (`MemoryBanks`, HAL, ou ambos); -- impacto esperado em overlay, telemetria e `AssetManager`. -*(Critérios atingidos em 2026-04-10)* diff --git a/discussion/workflow/decisions/DEC-0012-asset-manager-bank-telemetry-slot-contract.md b/discussion/workflow/decisions/DEC-0012-asset-manager-bank-telemetry-slot-contract.md deleted file mode 100644 index 03089200..00000000 --- a/discussion/workflow/decisions/DEC-0012-asset-manager-bank-telemetry-slot-contract.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -id: DEC-0012 -ticket: generic-memory-bank-slot-contract -title: Decision - Asset Manager Bank Telemetry Slot Contract -status: accepted -created: 2026-04-10 -updated: 2026-04-10 -agenda: AGD-0024 -tags: [runtime, asset, memory-bank, slots, host, telemetry] ---- - -# Decision - Asset Manager Bank Telemetry Slot Contract - -## Status -**Accepted** - -## Contexto -AGD-0024 fechou a mudança do contrato de banks de um modelo orientado a bytes para um modelo orientado a slots. A agenda também fechou que `BankPolicy` e `BankStats` não são base aceitável para a nova superfície visível e que a telemetria operacional consumida por host e overlay deve sair diretamente do `AssetManager`. - -Os pontos que a agenda resolveu e que esta decisão precisa cristalizar sem ambiguidade são: - -- o contrato visível é `slot-first`; -- o resumo visível por bank usa apenas `bank_type`, `used_slots` e `total_slots`; -- o detalhamento operacional ocorre por enum de slot; -- `GLYPH` e `SOUNDS` são os nomes canônicos do domínio; -- `GFX` e `AUD` não são nomes canônicos do contrato; -- a certificação deixa de usar bytes e passa a usar limites por slots; -- a genericidade principal do contrato visível não reside em `MemoryBanks`. - -## Decisao -1. O contrato visível de telemetria de banks MUST ser exposto diretamente por `AssetManager`. -2. O contrato visível de telemetria de banks MUST NOT ter `MemoryBanks` como superfície principal de exposição. `MemoryBanks` MAY manter detalhes internos de suporte, mas o ponto canônico de consumo visível do sistema SHALL ser `AssetManager`. -3. O resumo canônico por bank MUST usar somente os campos `bank_type`, `used_slots` e `total_slots`, no formato: - -```rust -pub struct BankTelemetry { - pub bank_type: BankType, - pub used_slots: usize, - pub total_slots: usize, -} -``` - -4. O contrato visível de telemetria de banks MUST ser `slot-first` e MUST NOT depender de contagens de bytes. -5. `bank_type` MUST usar nomes canônicos do domínio. Para os banks atuais, os nomes canônicos são `GLYPH` e `SOUNDS`. -6. `GFX` e `AUD` MUST NOT aparecer como nomes canônicos do contrato genérico de banks. Eles MAY existir apenas como rótulos de apresentação, quando estritamente necessário fora do contrato canônico. -7. `BankPolicy` e `BankStats` MUST ser removidos completamente do caminho do contrato visível de telemetria de banks e MUST NOT permanecer como modelagem principal desse domínio exposto. -8. O overlay do host MUST consumir a telemetria exposta por `AssetManager` e MUST NOT manter lógica hardcoded dependente de bancos específicos para calcular ocupação principal. -9. O detalhamento operacional por slot MUST ser definido por enum de slot, e qualquer inspeção detalhada de ocupação SHALL seguir esse modelo, não um detalhamento baseado em bytes. -10. As regras de certificação `max_gfx_bytes` e `max_audio_bytes` MUST ser removidas. -11. A certificação de banks MUST migrar para limites por slots, usando nomes canônicos de bank, tais como: - - `max_glyph_slots_used` - - `max_sound_slots_used` -12. Qualquer contabilização residual em bytes MAY sobreviver apenas como detalhe interno de implementação, quando estritamente necessária, e MUST NOT permanecer no contrato visível de telemetria de banks. - -## Rationale -- Slots são a unidade operacional real percebida por host, overlay e depuração de banks. -- `AssetManager` é o ponto que já conhece a ocupação efetiva dos banks e, portanto, é o lugar correto para expor o resumo visível. -- Remover bytes do contrato visível evita uma telemetria enganosa e elimina a ambiguidade que a agenda abriu para resolver. -- Fixar `GLYPH` e `SOUNDS` como nomes canônicos evita contaminar o contrato com apelidos de apresentação. -- Fixar enum de slot como detalhamento operacional evita reabrir a discussão sob outra forma durante a implementação. -- Migrar certificação para slots mantém o contrato exposto, o overlay e os limites técnicos usando a mesma semântica. - -## Invariantes / Contrato -- A telemetria de banks exposta ao restante do sistema sai de `AssetManager`. -- O contrato visível principal não reside em `MemoryBanks`. -- Cada entrada de telemetria de bank informa somente `bank_type`, `used_slots` e `total_slots`. -- O contrato canônico usa `GLYPH` e `SOUNDS`. -- O detalhamento operacional de slots usa enum de slot. -- O overlay não depende de bytes para mostrar ocupação de banks. -- A certificação de banks não depende de bytes. - -## Impactos -- **AssetManager:** deve expor `Vec` ou equivalente direto como superfície canônica visível. -- **MemoryBanks:** pode continuar como suporte interno, mas não deve concentrar o contrato visível principal de telemetria. -- **HAL / Bridges:** precisam alinhar qualquer interface consumidora ao contrato `slot-first`. -- **Overlay:** deve iterar a telemetria de banks do `AssetManager` e parar de recomputar a ocupação principal a partir de bytes. -- **Certifier:** precisa trocar limites de bytes por limites de slots para banks. -- **Legado:** `BankPolicy`, `BankStats`, `max_gfx_bytes` e `max_audio_bytes` precisam ser removidos do caminho canônico dessa capacidade. - -## Referencias -- `AGD-0024`: Generic Memory Bank Slot Contract. -- `DEC-0010`: Overlay Log Metric Uses Last Completed Frame. - -## Propagacao Necessaria -1. O plano de execução deve refatorar `AssetManager`, `MemoryBanks`, HAL/bridges, overlay e certificação sem reabrir a arquitetura base. -2. O caminho de telemetria de banks baseado em bytes deve ser removido do contrato visível. -3. O detalhamento operacional por enum de slot deve ser propagado para os pontos que inspecionam ocupação detalhada. -4. A certificação de banks deve migrar de limites em bytes para limites em slots. - -## Revision Log -- 2026-04-10: Initial decision emitted from `AGD-0024`. -- 2026-04-10: Decision tightened to align explicitly with agenda closure on `AssetManager` ownership, slot-enum operational detail, and `MemoryBanks` non-canonical residency. diff --git a/discussion/workflow/plans/PLN-0010-asset-manager-bank-telemetry-slot-contract.md b/discussion/workflow/plans/PLN-0010-asset-manager-bank-telemetry-slot-contract.md deleted file mode 100644 index 3b17cf2f..00000000 --- a/discussion/workflow/plans/PLN-0010-asset-manager-bank-telemetry-slot-contract.md +++ /dev/null @@ -1,194 +0,0 @@ ---- -id: PLN-0010 -ticket: generic-memory-bank-slot-contract -title: PR/Plan - Asset Manager Bank Telemetry Slot Contract -status: in_progress -created: 2026-04-10 -completed: -tags: [runtime, asset, memory-bank, slots, host, telemetry, certification] ---- - -## Briefing - -Implement `DEC-0012` by replacing the current byte-oriented bank telemetry path with a slot-first contract exposed directly by `AssetManager`. The execution MUST remove `BankPolicy` and `BankStats` from the visible telemetry path, keep canonical bank names aligned with `BankType` (`GLYPH`, `SOUNDS`), make the host overlay consume the new `AssetManager` summary, and migrate bank certification from byte limits to slot limits. - -## Decisions de Origem - -- `DEC-0012` - Asset Manager Bank Telemetry Slot Contract - -## Alvo - -Deliver a canonical bank telemetry path with these properties: - -- `AssetManager` exposes the visible per-bank summary. -- The visible summary shape is slot-first and limited to `bank_type`, `used_slots`, and `total_slots`. -- Detailed inspection remains slot-based through `SlotRef` / slot enums, not byte-based accounting. -- Host overlay and certification consume the new model. -- Legacy byte-oriented bank telemetry fields and limits are removed from the canonical path. - -## Escopo - -### Included - -- Add a canonical `BankTelemetry` type to the shared HAL asset contract. -- Add an `AssetBridge` method for bank telemetry summaries exposed by `AssetManager`. -- Refactor `AssetManager` in `crates/console/prometeu-drivers` to compute slot-first bank telemetry. -- Remove `BankStats` from the visible bank telemetry path and stop using it for overlay and certification. -- Remove `BankPolicy` as the main modeling surface used to describe visible bank telemetry. -- Keep detailed slot inspection on explicit slot references instead of bank byte summaries. -- Update runtime telemetry / certification to track `max_glyph_slots_used` and `max_sound_slots_used`. -- Update host overlay consumers to render bank occupancy from the new `AssetManager` summary. -- Update runtime specs so the published contract describes slot-first bank telemetry and slot-based certification. - -## Fora de Escopo - -- Reopening the base architectural decision about whether the visible summary belongs in `AssetManager`. -- Introducing new bank categories beyond the current `GLYPH` and `SOUNDS`. -- Reworking unrelated asset loading semantics, cartridge payload layout, or host UI design beyond adapting bank telemetry consumption. -- Removing all internal byte accounting if some private implementation detail still needs it temporarily. - -## Plano de Execucao - -### Step 1 - Lock the shared contract in HAL - -**What:** -Define the canonical shared types and trait surface for slot-first bank telemetry. - -**How:** -Add `BankTelemetry` to `crates/console/prometeu-hal/src/asset.rs` using `bank_type`, `used_slots`, and `total_slots`. Update `crates/console/prometeu-hal/src/asset_bridge.rs` so the visible bridge exposes a bank telemetry summary method from `AssetManager`. Remove or deprecate `BankStats` from the visible bridge path so downstream callers stop depending on byte-oriented bank summaries. - -**File(s):** -- `crates/console/prometeu-hal/src/asset.rs` -- `crates/console/prometeu-hal/src/asset_bridge.rs` - -**Depends on:** -- None - -### Step 2 - Refactor AssetManager to produce slot-first summaries - -**What:** -Move visible bank summary generation to a canonical `AssetManager` slot telemetry path. - -**How:** -Replace `bank_info(BankType) -> BankStats` with a summary path that reports only slot occupancy for each canonical bank type. Compute `used_slots` from the slot arrays already owned by `AssetManager` (`gfx_slots`, `sound_slots`) or equivalent canonical occupancy state. Keep detailed per-slot inspection in `slot_info(SlotRef)`. Remove `BankPolicy` and its byte counters as the visible modeling surface for bank telemetry; if any internal storage helper remains temporarily, it must not leak into the shared contract. - -**File(s):** -- `crates/console/prometeu-drivers/src/asset.rs` -- `crates/console/prometeu-drivers/src/memory_banks.rs` - -**Depends on:** -- Step 1 - -### Step 3 - Migrate runtime and host consumers to the new summary - -**What:** -Replace every bank summary consumer that still expects byte-oriented telemetry. - -**How:** -Update runtime and host callers to consume `BankTelemetry` from `AssetManager` instead of `BankStats`. Replace any direct `bank_info(BankType)` callsites with the new canonical summary path. Preserve slot-level inspection through `slot_info(SlotRef)` where detailed occupancy is needed. The host overlay must render bank occupancy from the `AssetManager` summary and must not reconstruct primary bank occupancy from bytes. - -**File(s):** -- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs` -- `crates/host/prometeu-host-desktop-winit/src/overlay.rs` -- Any additional callsites found through `rg 'bank_info|BankStats' crates` - -**Depends on:** -- Step 2 - -### Step 4 - Replace certification byte limits with slot limits - -**What:** -Move bank certification from byte ceilings to slot ceilings. - -**How:** -Replace `max_gfx_bytes` and `max_audio_bytes` in telemetry / certification configuration and evaluation with slot-based limits such as `max_glyph_slots_used` and `max_sound_slots_used`. Update runtime accounting to record the maximum occupied slot count per bank during execution. Remove byte-limit evaluation from the bank certification path. - -**File(s):** -- `crates/console/prometeu-hal/src/telemetry.rs` -- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs` - -**Depends on:** -- Step 3 - -### Step 5 - Remove residual canonical-path names and semantics that conflict with DEC-0012 - -**What:** -Eliminate remaining visible-path terminology and structures that preserve the old model. - -**How:** -Ensure no visible bank telemetry path still uses `GFX` / `AUD` as canonical names, `BankStats` as the summary type, or byte fields as the public bank occupancy contract. Keep `GLYPH` and `SOUNDS` aligned with the existing `BankType` enum. If bridges, docs, or helper APIs still expose the old path, remove or rename them in the same change set so the canonical path is unambiguous. - -**File(s):** -- `crates/console/prometeu-hal/src/asset.rs` -- `crates/console/prometeu-hal/src/asset_bridge.rs` -- `crates/console/prometeu-drivers/src/asset.rs` -- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs` -- `crates/host/prometeu-host-desktop-winit/src/overlay.rs` - -**Depends on:** -- Step 4 - -### Step 6 - Update published specifications - -**What:** -Align canonical docs with the implemented slot-first bank contract. - -**How:** -Update runtime specs to state that bank telemetry is exposed from `AssetManager`, that the published per-bank summary is slot-first, that detailed occupancy inspection remains slot-based, and that certification uses slot ceilings instead of byte ceilings. Remove residual published references to `max_gfx_bytes`, `max_audio_bytes`, or byte-oriented bank summaries in canonical specs. - -**File(s):** -- `docs/specs/runtime/15-asset-management.md` -- `docs/specs/runtime/10-debug-inspection-and-profiling.md` -- Any additional runtime spec file that still documents byte-based bank certification or overlay bank summary consumption - -**Depends on:** -- Step 5 - -## Criterios de Aceite - -- [ ] `AssetManager` is the canonical visible source of bank telemetry. -- [ ] The visible bank summary contract uses only `bank_type`, `used_slots`, and `total_slots`. -- [ ] Canonical bank names in the visible contract are `GLYPH` and `SOUNDS`. -- [ ] `BankStats` is no longer used as the visible bank telemetry summary type. -- [ ] `BankPolicy` is not the main visible modeling surface for bank telemetry. -- [ ] Host overlay bank occupancy uses the new `AssetManager` bank summary. -- [ ] Detailed occupancy inspection remains slot-based via slot references or equivalent slot enums. -- [ ] `max_gfx_bytes` and `max_audio_bytes` are removed from bank certification. -- [ ] Slot-based bank certification limits exist and are enforced. -- [ ] Published runtime specs describe the slot-first contract and slot-based certification model. - -## Tests / Validacao - -### Unit Tests - -- Add or update tests in `crates/console/prometeu-drivers/src/asset.rs` to verify the bank summary reports correct `used_slots` and `total_slots` for `GLYPH` and `SOUNDS`. -- Add or update tests in `crates/console/prometeu-hal/src/telemetry.rs` to verify slot-based certification thresholds trigger correctly and byte-based limits no longer exist in the bank path. -- Keep slot inspection tests proving `slot_info(SlotRef)` remains the detailed inspection mechanism. - -### Integration Tests - -- Run `cargo test -p prometeu-drivers`. -- Run `cargo test -p prometeu-hal`. -- Run `cargo test -p prometeu-system`. -- Run `cargo test -p prometeu-host-desktop-winit` if overlay bank telemetry callsites are changed there. -- Run `cargo check` for the full touched workspace if cross-crate API changes make targeted tests insufficient. - -### Manual Verification - -- Start the desktop host and confirm the overlay shows per-bank occupancy using slot counts, not bytes. -- Confirm the overlay labels use `GLYPH` and `SOUNDS` or approved presentation labels derived from those canonical bank types. -- Confirm certification output reports slot-limit violations and no longer reports `max_gfx_bytes` / `max_audio_bytes`. -- Confirm detailed slot inspection still works for both glyph and sound slots. - -## Dependencies - -- `DEC-0012` remains accepted and unchanged. -- Existing `BankType` enum values remain `GLYPH` and `SOUNDS`. -- `AssetManager` remains the asset-domain owner for slot occupancy summaries. - -## Riscos - -- Cross-crate trait changes in `AssetBridge` may create a wider refactor than the bank telemetry callsites initially suggest. -- Removing `BankStats` from the visible path may expose hidden byte-based assumptions in runtime telemetry, overlay formatting, or tests. -- Certification migration may fail partially if slot maxima are recorded in one layer while enforcement still reads old byte fields in another layer. -- If byte accounting is still needed internally during the refactor, the implementation can accidentally leak that detail back into public interfaces unless the change set is kept cohesive.