From 4ee7eff2fb4542818a7b1ddf2895ad63d1077d8d Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Sun, 19 Apr 2026 08:50:54 +0100 Subject: [PATCH] [PERF] Runtime Introspection Syscalls --- .../.backups/index.ndjson.20260419-085004.bak | 29 ++++ discussion/index.ndjson | 4 +- .../LSN-0034-host-owned-debug-boundaries.md | 55 ++++++++ ...011-perf-runtime-introspection-syscalls.md | 125 ------------------ ...0009-host-owned-debug-and-certification.md | 99 -------------- ...PLN-0030-dec9-spec-boundary-propagation.md | 86 ------------ .../PLN-0031-dec9-runtime-bank-abi-cleanup.md | 85 ------------ ...st-debugger-and-certification-alignment.md | 84 ------------ 8 files changed, 86 insertions(+), 481 deletions(-) create mode 100644 discussion/.backups/index.ndjson.20260419-085004.bak create mode 100644 discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md delete mode 100644 discussion/workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md delete mode 100644 discussion/workflow/decisions/DEC-0009-host-owned-debug-and-certification.md delete mode 100644 discussion/workflow/plans/PLN-0030-dec9-spec-boundary-propagation.md delete mode 100644 discussion/workflow/plans/PLN-0031-dec9-runtime-bank-abi-cleanup.md delete mode 100644 discussion/workflow/plans/PLN-0032-dec9-host-debugger-and-certification-alignment.md diff --git a/discussion/.backups/index.ndjson.20260419-085004.bak b/discussion/.backups/index.ndjson.20260419-085004.bak new file mode 100644 index 00000000..0b53408d --- /dev/null +++ b/discussion/.backups/index.ndjson.20260419-085004.bak @@ -0,0 +1,29 @@ +{"type":"meta","next_id":{"DSC":29,"AGD":29,"DEC":18,"PLN":33,"LSN":34,"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":"review","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-04-19","tags":["perf","runtime","syscall","telemetry","debug","asset"],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-04-18"}],"decisions":[{"id":"DEC-0009","file":"workflow/decisions/DEC-0009-host-owned-debug-and-certification.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-19","ref_agenda":"AGD-0011"}],"plans":[{"id":"PLN-0030","file":"workflow/plans/PLN-0030-dec9-spec-boundary-propagation.md","status":"done","created_at":"2026-04-19","updated_at":"2026-04-19","ref_decisions":["DEC-0009"]},{"id":"PLN-0031","file":"workflow/plans/PLN-0031-dec9-runtime-bank-abi-cleanup.md","status":"done","created_at":"2026-04-19","updated_at":"2026-04-19","ref_decisions":["DEC-0009"]},{"id":"PLN-0032","file":"workflow/plans/PLN-0032-dec9-host-debugger-and-certification-alignment.md","status":"done","created_at":"2026-04-19","updated_at":"2026-04-19","ref_decisions":["DEC-0009"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0013","status":"done","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":[],"decisions":[],"plans":[],"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":"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-0025","status":"done","ticket":"scene-bank-and-viewport-cache-refactor","title":"Scene Bank and Viewport Cache Refactor","created_at":"2026-04-11","updated_at":"2026-04-14","tags":["gfx","tilemap","runtime","render"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"lessons/DSC-0025-scene-bank-and-viewport-cache-refactor/LSN-0030-canonical-scene-cache-and-resolver-split.md","status":"done","created_at":"2026-04-14","updated_at":"2026-04-14"}]} +{"type":"discussion","id":"DSC-0026","status":"done","ticket":"render-all-scene-cache-and-camera-integration","title":"Integrate render_all with Scene Cache and Camera","created_at":"2026-04-14","updated_at":"2026-04-18","tags":["gfx","runtime","render","camera","scene"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0031","file":"lessons/DSC-0026-render-all-scene-cache-and-camera-integration/LSN-0031-frame-composition-belongs-above-the-render-backend.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]} +{"type":"discussion","id":"DSC-0027","status":"done","ticket":"frame-composer-public-syscall-surface","title":"Agenda - FrameComposer Public Syscall Surface","created_at":"2026-04-17","updated_at":"2026-04-18","tags":["gfx","runtime","syscall","abi","frame-composer","scene","camera","sprites"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0032","file":"lessons/DSC-0027-frame-composer-public-syscall-surface/LSN-0032-public-abi-must-follow-the-canonical-service-boundary.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]} +{"type":"discussion","id":"DSC-0028","status":"done","ticket":"deferred-overlay-and-primitive-composition","title":"Deferred Overlay and Primitive Composition over FrameComposer","created_at":"2026-04-18","updated_at":"2026-04-18","tags":["gfx","runtime","render","frame-composer","overlay","primitives","hud"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0033","file":"lessons/DSC-0028-deferred-overlay-and-primitive-composition/LSN-0033-debug-primitives-should-be-a-final-overlay-not-part-of-game-composition.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]} +{"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 0b53408d..d86c5efc 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,4 +1,4 @@ -{"type":"meta","next_id":{"DSC":29,"AGD":29,"DEC":18,"PLN":33,"LSN":34,"CLSN":1}} +{"type":"meta","next_id":{"DSC":29,"AGD":29,"DEC":18,"PLN":33,"LSN":35,"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"}]} @@ -14,7 +14,7 @@ {"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":"review","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-04-19","tags":["perf","runtime","syscall","telemetry","debug","asset"],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-04-18"}],"decisions":[{"id":"DEC-0009","file":"workflow/decisions/DEC-0009-host-owned-debug-and-certification.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-19","ref_agenda":"AGD-0011"}],"plans":[{"id":"PLN-0030","file":"workflow/plans/PLN-0030-dec9-spec-boundary-propagation.md","status":"done","created_at":"2026-04-19","updated_at":"2026-04-19","ref_decisions":["DEC-0009"]},{"id":"PLN-0031","file":"workflow/plans/PLN-0031-dec9-runtime-bank-abi-cleanup.md","status":"done","created_at":"2026-04-19","updated_at":"2026-04-19","ref_decisions":["DEC-0009"]},{"id":"PLN-0032","file":"workflow/plans/PLN-0032-dec9-host-debugger-and-certification-alignment.md","status":"done","created_at":"2026-04-19","updated_at":"2026-04-19","ref_decisions":["DEC-0009"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0012","status":"done","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-04-19","tags":["perf","runtime","syscall","telemetry","debug","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0034","file":"lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md","status":"done","created_at":"2026-04-19","updated_at":"2026-04-19"}]} {"type":"discussion","id":"DSC-0013","status":"done","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":[],"decisions":[],"plans":[],"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":"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-0025","status":"done","ticket":"scene-bank-and-viewport-cache-refactor","title":"Scene Bank and Viewport Cache Refactor","created_at":"2026-04-11","updated_at":"2026-04-14","tags":["gfx","tilemap","runtime","render"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"lessons/DSC-0025-scene-bank-and-viewport-cache-refactor/LSN-0030-canonical-scene-cache-and-resolver-split.md","status":"done","created_at":"2026-04-14","updated_at":"2026-04-14"}]} diff --git a/discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md b/discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md new file mode 100644 index 00000000..8234b304 --- /dev/null +++ b/discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md @@ -0,0 +1,55 @@ +--- +id: LSN-0034 +ticket: perf-runtime-introspection-syscalls +title: Host-Owned Debug Boundaries and Cheap Machine Diagnostics +created: 2026-04-19 +tags: [runtime, host, debug, certification, telemetry, abi] +--- + +## Context + +`DSC-0012` resolved a recurring ambiguity in PROMETEU: whether development diagnostics should be treated as part of the guest/runtime contract or as host tooling concerns. The codebase already had host overlay rendering, atomic telemetry snapshots, and slot-first bank telemetry, but the runtime still exposed JSON-formatted bank inspection syscalls. + +The completed work converged specs, runtime ABI, and host debugger behavior around a single boundary: rich diagnostics belong to the host, while the runtime exports only bounded machine-facing summaries. + +## Key Decisions + +### Host-Owned Debug and Certification (`DEC-0009`) + +**What:** +Debug tooling and certification are host-owned concerns. Guest-visible debug convenience APIs are not part of the long-term runtime ABI. + +**Why:** +Development inspection, profiling, and certification analysis happen on desktop host environments, not on production handheld/runtime targets. Keeping those concerns in the guest ABI forces production execution to carry tooling-oriented surface area and cost. + +**Trade-offs:** +The runtime gives up general introspection syscalls, so host tooling must consume telemetry and internal host/runtime integration points directly. In exchange, the public ABI becomes cheaper, narrower, and easier to reason about. + +## Patterns and Algorithms + +- Treat diagnostics as a layered boundary: + The runtime owns deterministic counters, bounded summaries, and machine-facing operational signals. + The host owns rendering, protocol projection, certification output, and rich inspection UX. + +- Prefer cheap structured values over textual debug payloads: + If a machine-facing diagnostic survives, it should return small canonical stack values such as `(used_slots, total_slots)`, not JSON blobs. + +- Use one telemetry source for all host consumers: + Atomic telemetry snapshots should feed debugger streaming, overlays, and certification evaluation so the platform does not fork multiple diagnostic pipelines. + +- Keep telemetry slot-first when the real machine contract is slot-first: + Bank occupancy was correctly modeled as slot usage, so the surviving public summary stayed aligned with that semantic model instead of byte-oriented totals or slot-detail dumps. + +## Pitfalls + +- Do not let host-only needs backdoor themselves into the guest ABI as "temporary" debug syscalls. They tend to linger and become accidental contract. + +- Do not use JSON-on-the-wire as a fallback ABI for runtime inspection. It is easy to add, but it creates unbounded cost and weakens the canonical machine model. + +- Do not update only specs or only code. This boundary needed spec propagation, runtime ABI cleanup, and host debugger alignment together to avoid split-brain behavior. + +## Takeaways + +- Debug and certification pipelines should be modeled as host products that consume runtime telemetry, not as guest features. +- Surviving machine diagnostics must be justified by operational need and expressed as bounded structured values. +- The clean boundary is: runtime produces telemetry, host interprets and presents it. diff --git a/discussion/workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md b/discussion/workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md deleted file mode 100644 index d902766f..00000000 --- a/discussion/workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -id: AGD-0011 -ticket: perf-runtime-introspection-syscalls -title: Agenda - [PERF] Runtime Introspection Syscalls -status: accepted -created: 2026-03-27 -resolved: 2026-04-18 -decision: DEC-0009 -tags: [perf, runtime, syscall, telemetry, debug, asset] ---- - -# Agenda - [PERF] Runtime Introspection Syscalls - -## Contexto - -O runtime ainda expõe `Syscall::BankInfo` e `Syscall::BankSlotInfo` como chamadas que serializam payloads JSON em tempo de dispatch e retornam `string` ao guest. - -Hoje o ponto concreto é este: - -- [`dispatch.rs`]() monta `serde_json::to_string(...)` para `BankTelemetry` e `slot_info`. - -Ao mesmo tempo, a arquitetura em volta já convergiu em outras frentes: - -- o contrato canônico de telemetria visível é `slot-first`, com `BankTelemetry { bank_type, used_slots, total_slots }`, em [`15-asset-management.md`](); -- a observabilidade de debug e profiling deve preferir `AtomicTelemetry` e `snapshot()` lock-free, em [`10-debug-inspection-and-profiling.md`](); -- o runtime nao deve assumir responsabilidade por HUD/renderizacao/formatacao textual de debug, em [`10-debug-inspection-and-profiling.md`](); -- a ABI canonica de syscalls passou a enfatizar shape explicito e `status-first` quando ha falha operacional observavel, em [`16-host-abi-and-syscalls.md`](). - -Em outras palavras: a agenda continua relevante, mas parte do enquadramento original envelheceu porque o repositorio ja escolheu direcao arquitetural para observabilidade, overlay e telemetria. - -## Problema - -Ainda existe uma area sem fechamento normativo: qual deve ser o papel de `bank.info` e `bank.slot_info` na ABI publica do guest agora que a arquitetura canônica convergiu para telemetria atomica, shape slot-first e isolamento host-side de debug. - -O problema nao e mais "se observabilidade precisa ser barata"; isso ja foi respondido por outras discussoes. O problema agora e: - -- se essas syscalls devem continuar existindo como superficie publica do guest; -- se o retorno em JSON ainda e aceitavel na ABI v1; -- se detalhamento por slot pertence ao guest, ao host/debugger, ou a ambos com contratos distintos. - -## Pontos Criticos - -- `BankInfo` ainda retorna string JSON apesar de o contrato semantico subjacente ja estar estabilizado como `BankTelemetry`. -- `BankSlotInfo` mistura inspecao detalhada com uma ABI opaca baseada em serializacao textual. -- o custo de introspecao no dispatch continua ocorrendo no mesmo caminho operacional das demais syscalls. -- manter JSON on-the-wire cria desvio em relacao ao restante da ABI, que privilegia shape explicito e tipos mais estaveis. -- remover ou restringir essas syscalls impacta carts, tooling de debug e possivel expectativa de introspecao in-guest. - -## Opcoes - -### Opcao A - Manter as syscalls publicas como estao - -- **Abordagem:** preservar `bank.info` e `bank.slot_info` com retorno JSON `string`. -- **Pro:** zero migracao imediata; continua simples para scripts ou carts experimentais consumirem introspecao textual. -- **Contra:** perpetua uma excecao arquitetural na ABI; mantem alocacao/serializacao no dispatch; reforca uso de debug como se fosse superficie operacional normal. -- **Risco:** cristalizar um contrato que conflita com a direcao atual de telemetria atomica e status-first. - -### Opcao B - Manter publicas, mas migrar para shape canonico barato - -- **Abordagem:** preservar a superficie guest, mas substituir JSON por retorno estruturado em slots, com shape canonico alinhado a `BankTelemetry` e a uma forma definida para detalhe por slot. -- **Pro:** reduz custo e aproxima a ABI das regras normativas atuais. -- **Contra:** exige redesenho de retorno, versao ou migracao de compatibilidade; `BankSlotInfo` ainda precisa justificar por que detalhamento fino deve continuar acessivel ao guest. -- **Risco:** podemos acabar mantendo uma superficie publica que o host/debugger deveria possuir sozinho. - -### Opcao C - Reclassificar como superficie de debug/host e retirar da ABI publica do guest - -- **Abordagem:** tratar resumo e inspecao detalhada de bancos como parte da superficie de diagnostico/host, usando snapshots/telemetria do lado host, e remover ou despriorizar a exposicao textual ao guest. -- **Pro:** maximiza isolamento de custo; fica coerente com a separacao host overlay x machine surface; reduz risco de abuso por carts. -- **Contra:** carts deixam de usar introspecao detalhada diretamente; exige definir claramente se existe algum minimo diagnostico ainda permitido dentro da maquina. -- **Risco:** cortar superficie demais e perder uma ferramenta util para testes, scripts internos ou casos de certificacao in-guest. - -### Opcao D - Dividir resumo publico de detalhe privado - -- **Abordagem:** manter apenas um resumo publico barato e canônico para o guest, e mover introspecao detalhada por slot para host/debugger. -- **Pro:** alinha-se ao contrato slot-first ja aceito; separa "estado operacional visivel" de "inspecao profunda"; minimiza o custo permanente da ABI publica. -- **Contra:** adiciona uma fronteira nova que precisa ser especificada com rigor. -- **Risco:** sem um criterio claro, o "resumo publico" pode crescer de novo e virar uma API de debug disfarcada. - -## Sugestao / Recomendacao - -A direcao mais consistente hoje e a **Opcao D**. - -Recomendacao preliminar desta agenda: - -- `bank.info` nao deve permanecer como JSON textual; se continuar publica, deve convergir para shape canonico barato e explicitamente limitado ao resumo operacional; -- `bank.slot_info` tem forte indicio de pertencer mais a host/debugger do que a ABI publica geral do guest; -- o runtime nao deve pagar custo de formatacao textual em nome de tooling; -- qualquer superficie publica remanescente deve ser definida em termos de contrato estavel, nao de payload JSON oportunista; -- certificacao e overlay devem continuar consumindo a mesma semantica canônica de telemetria, nao uma API paralela ad hoc. - -Direcao adicional consolidada nesta revisao: - -- debug e introspecao detalhada devem ser tratados como responsabilidade do host, com foco principal no host desktop onde o tooling de desenvolvimento realmente roda; -- a runtime "real" nao deve carregar uma superficie de debug geral como parte do contrato operacional normal; -- se alguma telemetria permanecer visivel fora do host, ela deve existir apenas por necessidade operacional canonica e nao como ferramenta de debug generico. - -## Perguntas em Aberto - -- O guest precisa mesmo de introspecao detalhada por slot em v1, ou resumo por banco ja cobre o caso normativo? -- Se `bank.info` permanecer publica, o retorno deve ser `status + fields` ou apenas fields sem `status` por nao haver falha operacional relevante? -- `bank.slot_info` deve ser removida da ABI publica, versionada para debug, ou mantida apenas em tooling host? -- Existe algum consumidor real no repositorio que dependa do JSON atual, ou isso e apenas um legado sem usuarios? - -## Criterio para Encerrar - -Esta agenda pode ser encerrada quando houver acordo explicito sobre: - -- papel normativo de `bank.info` na ABI publica; -- destino de `bank.slot_info` como superficie publica ou privada; -- eliminacao, manutencao versionada ou justificativa formal para JSON on-the-wire; -- regra de custo aceitavel no dispatch para introspecao remanescente; -- propagacao necessaria em spec, runtime, host debugger e certificacao. - -## Resolution - -O direcionamento atual desta agenda passou a assumir que debug nao pertence a runtime operacional como capacidade geral. Debug e introspecao detalhada devem viver no host, especialmente no host desktop, e a runtime deve expor apenas o minimo contrato operacional que continue necessario fora desse contexto. - -Ainda falta fechar, em decisao normativa, se esse "minimo contrato operacional" inclui algum resumo publico de banco ou se toda a superficie `bank.info` / `bank.slot_info` deve sair da ABI publica do guest. - -Esta agenda fica aceita com o seguinte fechamento de discussao: - -- debug e certificacao sao preocupacoes de host, nao do guest; -- host desktop e o contexto principal para tooling de desenvolvimento, introspecao e emissao de certificados; -- a runtime operacional nao deve carregar uma superficie geral de debug; -- qualquer dado remanescente exposto pela runtime deve ser justificado como contrato operacional minimo e nao como conveniencia de tooling. diff --git a/discussion/workflow/decisions/DEC-0009-host-owned-debug-and-certification.md b/discussion/workflow/decisions/DEC-0009-host-owned-debug-and-certification.md deleted file mode 100644 index d1371936..00000000 --- a/discussion/workflow/decisions/DEC-0009-host-owned-debug-and-certification.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -id: DEC-0009 -ticket: perf-runtime-introspection-syscalls -title: Host-Owned Debug and Certification -status: accepted -created: 2026-04-18 -accepted: 2026-04-19 -agenda: AGD-0011 -plans: [PLN-0030, PLN-0031, PLN-0032] -tags: [perf, runtime, host, debug, certification, syscall, telemetry] ---- - -## Status - -Accepted - -Accepted normative decision derived from `AGD-0011`. It locks the boundary between runtime operational surface and host-owned development tooling. - -## Contexto - -The current runtime still exposes bank introspection syscalls that serialize JSON strings during dispatch. In parallel, the repository already converged on host-side debug overlay, atomic telemetry snapshots, and slot-first bank telemetry semantics. - -The remaining ambiguity was whether debug and certification should continue to exist as guest-visible runtime concerns or be treated as host responsibilities. - -This discussion is now closed at the architectural level: development diagnostics are host concerns, not guest concerns. - -## Decisao - -PROMETEU debug tooling and certification SHALL be host-owned concerns. - -Normative consequences: - -- the guest/runtime public operational contract MUST NOT include a general-purpose debug surface; -- certification MUST NOT be modeled as a guest-visible runtime feature; -- the desktop host SHALL be the primary environment for debug tooling, inspection, telemetry consumption, and certification output; -- the runtime MAY expose only the minimum machine-facing operational data that remains necessary outside host tooling; -- any remaining runtime-visible diagnostics MUST be justified as operational contract, not as generic debug convenience. - -For the bank introspection topic specifically: - -- `bank.slot_info` SHALL be treated as host/debug tooling surface and SHOULD NOT remain part of the general guest ABI; -- `bank.info` MUST NOT remain a JSON textual contract if it survives in any public form; -- if a public `bank.info` remains, it MUST be reduced to a canonical cheap operational summary aligned with the slot-first bank telemetry model; -- if no such operational need exists, `bank.info` SHOULD also leave the guest ABI. - -## Rationale - -This decision follows directly from the product reality of the platform: - -- end users on real handheld/runtime targets do not inspect debug data or certification reports; -- game development, jams, profiling, debugging, and certification analysis occur on PC/desktop; -- keeping debug and certification inside the guest/runtime surface makes production execution pay for tooling-oriented concerns; -- treating certification as a consumer of host-side debug/telemetry output keeps one diagnostic pipeline instead of duplicating machine and host responsibilities. - -The decision also aligns the runtime with prior convergence already visible in the repository: - -- host overlay lives outside the emulated framebuffer and outside the machine contract; -- telemetry is already snapshot-oriented and host-consumable; -- public bank telemetry semantics are already slot-first and narrower than arbitrary textual inspection payloads. - -## Invariantes / Contrato - -- Runtime operational behavior MUST remain independent from whether host debug tooling is active. -- Runtime production targets MUST NOT require debug surfaces to operate correctly. -- Certification generation MUST happen in the host layer. -- Host certification MAY consume the same telemetry/debug pipeline used for tooling and inspection. -- Runtime-visible diagnostics, if any remain, MUST be explicitly documented as operational ABI and MUST have bounded cost. -- JSON-on-the-wire debug payloads MUST NOT define the long-term public ABI. - -## Impactos - -- Specs must be updated so that debug and certification are described as host-owned concerns rather than guest/runtime features. -- The syscall surface must be reviewed to remove, restrict, or redesign `bank.info` and `bank.slot_info`. -- The host debugger/certification path becomes the canonical consumer of detailed inspection output. -- Any runtime code that formats debug payloads textually in dispatch becomes suspect and should be removed or reduced. -- Future plans must not reintroduce guest-facing debug APIs without a new explicit decision. - -## Referencias - -- `AGD-0011` -- `docs/specs/runtime/10-debug-inspection-and-profiling.md` -- `docs/specs/runtime/15-asset-management.md` -- `docs/specs/runtime/16-host-abi-and-syscalls.md` -- `docs/specs/runtime/16a-syscall-policies.md` -- `LSN-0026` -- `LSN-0027` -- `LSN-0029` - -## Propagacao Necessaria - -- Update runtime specs to move certification ownership to the host layer. -- Update runtime specs to narrow or remove guest-visible debug framing. -- Write an execution plan for syscall/spec/host propagation before implementation. -- Review runtime dispatch for `bank.info` / `bank.slot_info` and align the ABI with this boundary. - -## Revision Log - -- 2026-04-18: Initial draft from AGD-0011. -- 2026-04-19: Accepted and decomposed into `PLN-0030`, `PLN-0031`, and `PLN-0032`. diff --git a/discussion/workflow/plans/PLN-0030-dec9-spec-boundary-propagation.md b/discussion/workflow/plans/PLN-0030-dec9-spec-boundary-propagation.md deleted file mode 100644 index 68cba3ef..00000000 --- a/discussion/workflow/plans/PLN-0030-dec9-spec-boundary-propagation.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -id: PLN-0030 -ticket: perf-runtime-introspection-syscalls -title: DEC-0009 Spec Boundary Propagation -status: done -created: 2026-04-19 -completed: 2026-04-19 -tags: [runtime, spec, host, debug, certification, syscall] ---- - -## Briefing - -Propagate `DEC-0009` into the canonical runtime specifications so that debug tooling and certification are described as host-owned concerns, not guest/runtime feature surfaces. - -## Decisions de Origem - -- `DEC-0009` - Host-Owned Debug and Certification - -## Alvo - -Lock the written contract across the runtime specs before code execution starts, so implementation work does not reopen the architecture. - -## Escopo - -- update `docs/specs/runtime/10-debug-inspection-and-profiling.md` to narrow the runtime-visible diagnostics surface and state explicitly that detailed inspection and certification output are host-owned; -- update `docs/specs/runtime/15-asset-management.md` to keep bank telemetry slot-first and prohibit guest-visible debug-oriented bank inspection as a general ABI; -- update `docs/specs/runtime/16-host-abi-and-syscalls.md` so `bank.info` / `bank.slot_info` are either removed from the public syscall catalog or redefined only as bounded operational ABI; -- update `docs/specs/runtime/16a-syscall-policies.md` to reinforce that debug convenience APIs are not valid justification for guest-visible syscalls; -- align cross-references to existing host-overlay and telemetry chapters where they already define the canonical diagnostics pipeline. - -## Fora de Escopo - -- changing Rust code in `crates/`; -- introducing a new guest-facing inspection ABI; -- redesigning debugger transport or host protocol payload schemas. - -## Plano de Execucao - -### Step 1 - Rewrite the normative ownership language - -**What:** Rewrite the affected spec chapters so that debug tooling, rich inspection, and certification reporting are host-owned responsibilities. -**How:** Replace guest/runtime-centric wording in `10-debug-inspection-and-profiling.md` with host-owned framing, keeping runtime obligations limited to bounded telemetry production and deterministic machine behavior. -**File(s):** `docs/specs/runtime/10-debug-inspection-and-profiling.md` - -### Step 2 - Converge the asset/bank contract - -**What:** Align asset-management language with the decision that slot-first telemetry is the visible contract and bank inspection is not a general guest debug service. -**How:** Update the bank telemetry and diagnostics sections to describe the canonical operational summary, the absence of JSON textual bank ABI, and the host ownership of detailed slot inspection. -**File(s):** `docs/specs/runtime/15-asset-management.md` - -### Step 3 - Tighten the syscall chapter - -**What:** Remove ambiguity around `bank.info` and `bank.slot_info` in the public ABI contract. -**How:** Amend the host ABI and syscall policy chapters so they either remove those calls from the public surface or constrain any surviving `bank.info` form to a cheap, deterministic, non-JSON operational summary justified by machine needs. -**File(s):** `docs/specs/runtime/16-host-abi-and-syscalls.md`, `docs/specs/runtime/16a-syscall-policies.md` - -### Step 4 - Verify cross-chapter consistency - -**What:** Ensure no remaining chapter describes certification or debug tooling as runtime-owned functionality. -**How:** Review cross-references in nearby runtime chapters that mention certification, host tooling, or diagnostics and patch inconsistent wording where directly impacted by the edited contract. -**File(s):** `docs/specs/runtime/09-events-and-concurrency.md`, `docs/specs/runtime/11-portability-and-cross-platform-execution.md`, plus the edited primary chapters - -## Criterios de Aceite - -- `DEC-0009` is cited explicitly in the updated spec material. -- The specs state unambiguously that certification generation is host-owned. -- The specs no longer describe JSON-formatted bank inspection as part of the long-term public guest ABI. -- The public runtime contract for bank telemetry remains slot-first and bounded. -- The updated text is internally consistent across the touched runtime chapters. - -## Tests / Validacao - -- manual doc review of the edited chapters for contradictory wording about ownership; -- targeted search for `bank.info`, `bank.slot_info`, `certification`, and `debug` in `docs/specs/runtime/` to ensure the remaining text matches `DEC-0009`; -- verify that all new or changed published spec text remains in English. - -## Riscos - -- spec-only propagation may accidentally leave residual guest-oriented language that later reintroduces ABI ambiguity; -- over-editing adjacent chapters could broaden the scope beyond `DEC-0009`; -- under-specifying the surviving `bank.info` option could block the runtime ABI cleanup plan. - -## Dependencies - -- `DEC-0009` must remain accepted and unchanged while this plan is executed. -- This plan should complete before runtime syscall removal or narrowing work begins. diff --git a/discussion/workflow/plans/PLN-0031-dec9-runtime-bank-abi-cleanup.md b/discussion/workflow/plans/PLN-0031-dec9-runtime-bank-abi-cleanup.md deleted file mode 100644 index c24a8aeb..00000000 --- a/discussion/workflow/plans/PLN-0031-dec9-runtime-bank-abi-cleanup.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -id: PLN-0031 -ticket: perf-runtime-introspection-syscalls -title: DEC-0009 Runtime Bank ABI Cleanup -status: done -created: 2026-04-19 -completed: 2026-04-19 -tags: [runtime, syscall, abi, bank, telemetry, debug] ---- - -## Briefing - -Execute the runtime-side ABI cleanup mandated by `DEC-0009` by removing or narrowing guest-visible bank inspection syscalls and eliminating JSON formatting from dispatch. - -## Decisions de Origem - -- `DEC-0009` - Host-Owned Debug and Certification - -## Alvo - -Bring the public runtime syscall surface into compliance with the accepted decision while preserving any truly necessary cheap operational summary. - -## Escopo - -- review and update the public bank syscall registry in `crates/console/prometeu-hal/src/syscalls/domains/bank.rs`; -- refactor bank syscall dispatch in `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`; -- align runtime tests around the new ABI shape and the removal of JSON string payloads; -- keep internal asset telemetry and `slot_info` helpers available for host/runtime internals where they are still needed. - -## Fora de Escopo - -- changing the desktop debugger protocol payloads; -- introducing a new host transport; -- modifying unrelated asset loading semantics or slot ownership rules. - -## Plano de Execucao - -### Step 1 - Decide the surviving machine-facing bank surface - -**What:** Resolve the exact runtime-facing outcome for `bank.info` and `bank.slot_info` under the accepted decision. -**How:** Use the accepted spec text from `PLN-0030` as the source of truth and implement one of two bounded outcomes: remove both public syscalls, or keep only a cheap non-JSON `bank.info` summary if an operational use case remains documented. -**File(s):** `docs/specs/runtime/16-host-abi-and-syscalls.md`, `crates/console/prometeu-hal/src/syscalls/domains/bank.rs` - -### Step 2 - Remove JSON-on-the-wire dispatch behavior - -**What:** Eliminate textual JSON serialization from the runtime dispatch path. -**How:** Delete the `serde_json::to_string` bank inspection branches in `virtual_machine_runtime/dispatch.rs` and replace them with the chosen bounded ABI behavior from Step 1. -**File(s):** `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs` - -### Step 3 - Realign tests and syscall metadata - -**What:** Update test coverage and metadata assumptions to the new bank syscall contract. -**How:** Add or update tests for registry shape, return-slot behavior, and fault/status behavior so the runtime proves that debug-only bank inspection no longer leaks through the guest ABI. -**File(s):** `crates/console/prometeu-hal/src/syscalls/domains/bank.rs`, `crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs`, any syscall metadata tests discovered during execution - -### Step 4 - Preserve internal host-facing inspection sources - -**What:** Keep slot and bank telemetry available for host-owned tooling without re-exporting them as guest ABI. -**How:** Verify that `AssetManager` telemetry helpers and internal `slot_info` access remain usable by host/runtime internals after the public syscall cleanup. -**File(s):** `crates/console/prometeu-drivers/src/asset.rs`, related internal callers discovered during execution - -## Criterios de Aceite - -- The public bank syscall registry no longer exposes JSON-formatted debug inspection. -- `virtual_machine_runtime/dispatch.rs` no longer serializes bank telemetry or slot details into JSON strings for guest return values. -- Any surviving `bank.info` surface is cheap, deterministic, bounded, and documented as operational ABI. -- Guest code cannot access detailed slot inspection through a generic debug convenience syscall. -- Runtime tests cover the new ABI behavior. - -## Tests / Validacao - -- unit tests for syscall registry metadata and runtime dispatch behavior; -- targeted search for `serde_json::to_string`, `BankInfo`, and `BankSlotInfo` in the runtime crates after the refactor; -- run the affected Rust test suites for HAL/system crates that cover syscall dispatch and bank telemetry behavior. - -## Riscos - -- removing syscalls without finishing spec propagation first may create contract drift; -- keeping a reduced `bank.info` without a crisp return shape may preserve ambiguity; -- internal host tooling might still rely on code paths that currently sit behind the guest syscall implementation. - -## Dependencies - -- `PLN-0030` should land first or in lockstep so the code change follows published contract text. -- Host tooling migration work in `PLN-0032` may depend on internal inspection helpers preserved by this plan. diff --git a/discussion/workflow/plans/PLN-0032-dec9-host-debugger-and-certification-alignment.md b/discussion/workflow/plans/PLN-0032-dec9-host-debugger-and-certification-alignment.md deleted file mode 100644 index 36f21f55..00000000 --- a/discussion/workflow/plans/PLN-0032-dec9-host-debugger-and-certification-alignment.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -id: PLN-0032 -ticket: perf-runtime-introspection-syscalls -title: DEC-0009 Host Debugger and Certification Alignment -status: done -created: 2026-04-19 -completed: 2026-04-19 -tags: [host, debug, certification, telemetry, desktop] ---- - -## Briefing - -Align the desktop host debugger and certification pipeline with `DEC-0009` so detailed inspection and certification outputs are consumed from host-owned telemetry/debug flows rather than from guest-visible runtime APIs. - -## Decisions de Origem - -- `DEC-0009` - Host-Owned Debug and Certification - -## Alvo - -Make the desktop host the canonical consumer of runtime telemetry, certification configuration, and detailed inspection data after the guest ABI cleanup. - -## Escopo - -- review `crates/host/prometeu-host-desktop-winit/src/debugger.rs` for reliance on guest-facing inspection assumptions and document the intended host-owned data sources; -- review `crates/host/prometeu-host-desktop-winit/src/cap.rs` and certification wiring in `runner.rs` so certification remains fully host-generated; -- align any host-side contracts with the accepted spec and runtime ABI cleanup; -- add or update tests that prove certification/debug behavior does not depend on guest-visible debug syscalls. - -## Fora de Escopo - -- redesigning the external debugger client application; -- changing unrelated desktop rendering or overlay presentation behavior; -- adding new certification metrics beyond what existing telemetry already supports. - -## Plano de Execucao - -### Step 1 - Audit host data sources - -**What:** Identify where the desktop host already consumes telemetry and where it still implicitly depends on guest-oriented inspection concepts. -**How:** Review `debugger.rs`, `runner.rs`, and supporting modules for state, telemetry, certification, and inspection flows; record which inputs come from atomic telemetry, crash reports, or direct host/runtime internals. -**File(s):** `crates/host/prometeu-host-desktop-winit/src/debugger.rs`, `crates/host/prometeu-host-desktop-winit/src/runner.rs`, `crates/host/prometeu-host-desktop-winit/src/overlay.rs` - -### Step 2 - Lock certification ownership in host code - -**What:** Ensure certification remains generated and configured exclusively in the host layer. -**How:** Update certification setup and any related documentation/comments so host code owns report generation and consumes runtime telemetry snapshots rather than guest-facing diagnostic APIs. -**File(s):** `crates/host/prometeu-host-desktop-winit/src/cap.rs`, `crates/host/prometeu-host-desktop-winit/src/runner.rs` - -### Step 3 - Adjust debugger integration after ABI cleanup - -**What:** Keep rich inspection available to developer tooling after `PLN-0031` removes or narrows guest bank inspection syscalls. -**How:** Move any remaining detailed inspection dependence onto host-owned runtime access paths or protocol messages that do not reintroduce guest ABI surface. -**File(s):** `crates/host/prometeu-host-desktop-winit/src/debugger.rs`, related protocol or host integration files discovered during execution - -### Step 4 - Prove the boundary in tests - -**What:** Add evidence that host tooling and certification still work without guest-visible debug syscalls. -**How:** Extend host tests around debugger startup, telemetry streaming, and certification config loading, and add focused assertions that the host path depends on telemetry/internal access rather than guest ABI inspection. -**File(s):** `crates/host/prometeu-host-desktop-winit/src/debugger.rs`, `crates/host/prometeu-host-desktop-winit/src/runner.rs`, `crates/host/prometeu-host-desktop-winit/src/cap.rs` - -## Criterios de Aceite - -- The host debugger and certification pipeline are described and implemented as host-owned consumers. -- No host feature requires `bank.slot_info` or JSON `bank.info` to remain exposed to guest code. -- Certification configuration and report generation stay in host code. -- Host-side tests cover the intended telemetry/debug/certification path after ABI cleanup. - -## Tests / Validacao - -- run host crate tests covering debugger startup, command handling, and certification config loading; -- targeted search in the host crate for references to guest-visible bank inspection APIs after implementation; -- manual review that host comments and module responsibilities match `DEC-0009`. - -## Riscos - -- host code may still rely on implicit runtime internals that are not clearly documented; -- coupling host tooling migration to runtime ABI cleanup could stall both if sequencing is unclear; -- lack of explicit host-side test coverage may hide regressions until manual debugger use. - -## Dependencies - -- `PLN-0030` provides the published ownership model. -- `PLN-0031` defines the final runtime ABI boundary that host tooling must stop depending on.