[PERF] Runtime Introspection Syscalls

This commit is contained in:
2026-04-18 18:19:39 +01:00
parent 509b669db5
commit e895b01b8f
3 changed files with 195 additions and 44 deletions
@@ -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`](</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
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.