From e895b01b8f5394bbe811751005e8cb2aea630ebc Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Sat, 18 Apr 2026 18:19:39 +0100 Subject: [PATCH] [PERF] Runtime Introspection Syscalls --- discussion/index.ndjson | 4 +- ...011-perf-runtime-introspection-syscalls.md | 137 ++++++++++++------ ...0009-host-owned-debug-and-certification.md | 98 +++++++++++++ 3 files changed, 195 insertions(+), 44 deletions(-) create mode 100644 discussion/workflow/decisions/DEC-0009-host-owned-debug-and-certification.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 6c1c7a0d..c059777b 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,4 +1,4 @@ -{"type":"meta","next_id":{"DSC":29,"AGD":29,"DEC":17,"PLN":30,"LSN":34,"CLSN":1}} +{"type":"meta","next_id":{"DSC":29,"AGD":29,"DEC":18,"PLN":30,"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"}]} @@ -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":"open","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0012","status":"review","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-04-18","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":"review","created_at":"2026-04-18","updated_at":"2026-04-18","ref_agenda":"AGD-0011"}],"plans":[],"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"}]} diff --git a/discussion/workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md b/discussion/workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md index ab1e508c..d902766f 100644 --- a/discussion/workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md +++ b/discussion/workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md @@ -2,71 +2,124 @@ id: AGD-0011 ticket: perf-runtime-introspection-syscalls title: Agenda - [PERF] Runtime Introspection Syscalls -status: open +status: accepted created: 2026-03-27 -resolved: -decision: -tags: [] +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 -As syscalls de introspecao ainda carregam custo de serializacao e agregacao demais para algo que deveria ser observabilidade sob demanda. +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. -Hoje `BankInfo` e `BankSlotInfo` montam JSON por chamada e puxam dados potencialmente caros do asset manager. +O problema nao e mais "se observabilidade precisa ser barata"; isso ja foi respondido por outras discussoes. O problema agora e: -## Dor +- 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. -- tooling de debug pode contaminar custo percebido da runtime surface. -- serializacao de string/JSON vira alocacao no meio do dispatch. -- sem fronteira clara, apps podem abusar de syscalls de introspecao como se fossem baratas. +## Pontos Criticos -## Hotspots Atuais +- `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. -- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L481) -- [asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs#L618) +## Opcoes -## Alvo da Discussao +### Opcao A - Manter as syscalls publicas como estao -Separar claramente custo de introspecao/debug do custo da superficie operacional normal. +- **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. -## O Que Precisa Ser Definido +### Opcao B - Manter publicas, mas migrar para shape canonico barato -1. Papel dessas syscalls. - Decidir se `BankInfo`/`BankSlotInfo` sao: - - superficie publica normal; - - superficie de debug; - - superficie host/devtools apenas. +- **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. -2. Shape de retorno. - Definir se JSON continua existindo ou se v1 exige shape mais barato/canonico. +### Opcao C - Reclassificar como superficie de debug/host e retirar da ABI publica do guest -3. Caching. - Delimitar se snapshots de introspecao podem ser cacheados por frame. +- **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. -4. Limites de uso. - Decidir se o runtime deve impor throttling, budget ou feature gate de debug. +### Opcao D - Dividir resumo publico de detalhe privado -## Open Questions de Arquitetura +- **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. -1. Vale manter JSON na ABI do guest ou isso deveria ficar restrito ao host/debugger? -2. Existe um subconjunto de dados numericos suficiente para carts sem tooling externo? -3. O certifier deve observar essas chamadas como custo anormal de debug? +## Sugestao / Recomendacao -## Dependencias +A direcao mais consistente hoje e a **Opcao D**. -- `../specs/10-debug-inspection-and-profiling.md` -- `../specs/15-asset-management.md` -- `../specs/16-host-abi-and-syscalls.md` -- `../specs/16a-syscall-policies.md` +Recomendacao preliminar desta agenda: -## Criterio de Saida 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. -Pode virar PR quando houver decisao escrita sobre: +Direcao adicional consolidada nesta revisao: -- papel normativo de `BankInfo`/`BankSlotInfo`; -- permanencia ou remocao de JSON como shape de retorno; -- politica de cache/throttling; -- custo aceitavel de introspecao no dispatch. +- 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 new file mode 100644 index 00000000..a76688e6 --- /dev/null +++ b/discussion/workflow/decisions/DEC-0009-host-owned-debug-and-certification.md @@ -0,0 +1,98 @@ +--- +id: DEC-0009 +ticket: perf-runtime-introspection-syscalls +title: Host-Owned Debug and Certification +status: review +created: 2026-04-18 +accepted: +agenda: AGD-0011 +plans: [] +tags: [perf, runtime, host, debug, certification, syscall, telemetry] +--- + +## Status + +Review + +Normative draft derived from `AGD-0011`. It is intended to lock 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.