[PERF] Runtime Introspection Syscalls
This commit is contained in:
parent
c87a1b7f62
commit
4ee7eff2fb
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
29
discussion/.backups/index.ndjson.20260419-085004.bak
Normal file
29
discussion/.backups/index.ndjson.20260419-085004.bak
Normal file
@ -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"}]}
|
||||
@ -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"}]}
|
||||
|
||||
@ -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.
|
||||
@ -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`](</Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs:554>) 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`](</Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/15-asset-management.md:187>);
|
||||
- a observabilidade de debug e profiling deve preferir `AtomicTelemetry` e `snapshot()` lock-free, em [`10-debug-inspection-and-profiling.md`](</Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/10-debug-inspection-and-profiling.md:281>);
|
||||
- o runtime nao deve assumir responsabilidade por HUD/renderizacao/formatacao textual de debug, em [`10-debug-inspection-and-profiling.md`](</Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/10-debug-inspection-and-profiling.md:262>);
|
||||
- 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`](</Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/16-host-abi-and-syscalls.md:155>).
|
||||
|
||||
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.
|
||||
@ -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`.
|
||||
@ -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.
|
||||
@ -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.
|
||||
@ -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.
|
||||
Loading…
x
Reference in New Issue
Block a user