--- id: AGD-0011 ticket: perf-runtime-introspection-syscalls title: Agenda - [PERF] Runtime Introspection Syscalls status: accepted created: 2026-03-27 resolved: 2026-04-18 decision: DEC-0009 tags: [perf, runtime, syscall, telemetry, debug, asset] --- # Agenda - [PERF] Runtime Introspection Syscalls ## Contexto O runtime ainda expõe `Syscall::BankInfo` e `Syscall::BankSlotInfo` como chamadas que serializam payloads JSON em tempo de dispatch e retornam `string` ao guest. Hoje o ponto concreto é este: - [`dispatch.rs`]() monta `serde_json::to_string(...)` para `BankTelemetry` e `slot_info`. Ao mesmo tempo, a arquitetura em volta já convergiu em outras frentes: - o contrato canônico de telemetria visível é `slot-first`, com `BankTelemetry { bank_type, used_slots, total_slots }`, em [`15-asset-management.md`](); - a observabilidade de debug e profiling deve preferir `AtomicTelemetry` e `snapshot()` lock-free, em [`10-debug-inspection-and-profiling.md`](); - o runtime nao deve assumir responsabilidade por HUD/renderizacao/formatacao textual de debug, em [`10-debug-inspection-and-profiling.md`](); - a ABI canonica de syscalls passou a enfatizar shape explicito e `status-first` quando ha falha operacional observavel, em [`16-host-abi-and-syscalls.md`](). Em outras palavras: a agenda continua relevante, mas parte do enquadramento original envelheceu porque o repositorio ja escolheu direcao arquitetural para observabilidade, overlay e telemetria. ## Problema Ainda existe uma area sem fechamento normativo: qual deve ser o papel de `bank.info` e `bank.slot_info` na ABI publica do guest agora que a arquitetura canônica convergiu para telemetria atomica, shape slot-first e isolamento host-side de debug. O problema nao e mais "se observabilidade precisa ser barata"; isso ja foi respondido por outras discussoes. O problema agora e: - se essas syscalls devem continuar existindo como superficie publica do guest; - se o retorno em JSON ainda e aceitavel na ABI v1; - se detalhamento por slot pertence ao guest, ao host/debugger, ou a ambos com contratos distintos. ## Pontos Criticos - `BankInfo` ainda retorna string JSON apesar de o contrato semantico subjacente ja estar estabilizado como `BankTelemetry`. - `BankSlotInfo` mistura inspecao detalhada com uma ABI opaca baseada em serializacao textual. - o custo de introspecao no dispatch continua ocorrendo no mesmo caminho operacional das demais syscalls. - manter JSON on-the-wire cria desvio em relacao ao restante da ABI, que privilegia shape explicito e tipos mais estaveis. - remover ou restringir essas syscalls impacta carts, tooling de debug e possivel expectativa de introspecao in-guest. ## Opcoes ### Opcao A - Manter as syscalls publicas como estao - **Abordagem:** preservar `bank.info` e `bank.slot_info` com retorno JSON `string`. - **Pro:** zero migracao imediata; continua simples para scripts ou carts experimentais consumirem introspecao textual. - **Contra:** perpetua uma excecao arquitetural na ABI; mantem alocacao/serializacao no dispatch; reforca uso de debug como se fosse superficie operacional normal. - **Risco:** cristalizar um contrato que conflita com a direcao atual de telemetria atomica e status-first. ### Opcao B - Manter publicas, mas migrar para shape canonico barato - **Abordagem:** preservar a superficie guest, mas substituir JSON por retorno estruturado em slots, com shape canonico alinhado a `BankTelemetry` e a uma forma definida para detalhe por slot. - **Pro:** reduz custo e aproxima a ABI das regras normativas atuais. - **Contra:** exige redesenho de retorno, versao ou migracao de compatibilidade; `BankSlotInfo` ainda precisa justificar por que detalhamento fino deve continuar acessivel ao guest. - **Risco:** podemos acabar mantendo uma superficie publica que o host/debugger deveria possuir sozinho. ### Opcao C - Reclassificar como superficie de debug/host e retirar da ABI publica do guest - **Abordagem:** tratar resumo e inspecao detalhada de bancos como parte da superficie de diagnostico/host, usando snapshots/telemetria do lado host, e remover ou despriorizar a exposicao textual ao guest. - **Pro:** maximiza isolamento de custo; fica coerente com a separacao host overlay x machine surface; reduz risco de abuso por carts. - **Contra:** carts deixam de usar introspecao detalhada diretamente; exige definir claramente se existe algum minimo diagnostico ainda permitido dentro da maquina. - **Risco:** cortar superficie demais e perder uma ferramenta util para testes, scripts internos ou casos de certificacao in-guest. ### Opcao D - Dividir resumo publico de detalhe privado - **Abordagem:** manter apenas um resumo publico barato e canônico para o guest, e mover introspecao detalhada por slot para host/debugger. - **Pro:** alinha-se ao contrato slot-first ja aceito; separa "estado operacional visivel" de "inspecao profunda"; minimiza o custo permanente da ABI publica. - **Contra:** adiciona uma fronteira nova que precisa ser especificada com rigor. - **Risco:** sem um criterio claro, o "resumo publico" pode crescer de novo e virar uma API de debug disfarcada. ## Sugestao / Recomendacao A direcao mais consistente hoje e a **Opcao D**. Recomendacao preliminar desta agenda: - `bank.info` nao deve permanecer como JSON textual; se continuar publica, deve convergir para shape canonico barato e explicitamente limitado ao resumo operacional; - `bank.slot_info` tem forte indicio de pertencer mais a host/debugger do que a ABI publica geral do guest; - o runtime nao deve pagar custo de formatacao textual em nome de tooling; - qualquer superficie publica remanescente deve ser definida em termos de contrato estavel, nao de payload JSON oportunista; - certificacao e overlay devem continuar consumindo a mesma semantica canônica de telemetria, nao uma API paralela ad hoc. Direcao adicional consolidada nesta revisao: - debug e introspecao detalhada devem ser tratados como responsabilidade do host, com foco principal no host desktop onde o tooling de desenvolvimento realmente roda; - a runtime "real" nao deve carregar uma superficie de debug geral como parte do contrato operacional normal; - se alguma telemetria permanecer visivel fora do host, ela deve existir apenas por necessidade operacional canonica e nao como ferramenta de debug generico. ## Perguntas em Aberto - O guest precisa mesmo de introspecao detalhada por slot em v1, ou resumo por banco ja cobre o caso normativo? - Se `bank.info` permanecer publica, o retorno deve ser `status + fields` ou apenas fields sem `status` por nao haver falha operacional relevante? - `bank.slot_info` deve ser removida da ABI publica, versionada para debug, ou mantida apenas em tooling host? - Existe algum consumidor real no repositorio que dependa do JSON atual, ou isso e apenas um legado sem usuarios? ## Criterio para Encerrar Esta agenda pode ser encerrada quando houver acordo explicito sobre: - papel normativo de `bank.info` na ABI publica; - destino de `bank.slot_info` como superficie publica ou privada; - eliminacao, manutencao versionada ou justificativa formal para JSON on-the-wire; - regra de custo aceitavel no dispatch para introspecao remanescente; - propagacao necessaria em spec, runtime, host debugger e certificacao. ## Resolution O direcionamento atual desta agenda passou a assumir que debug nao pertence a runtime operacional como capacidade geral. Debug e introspecao detalhada devem viver no host, especialmente no host desktop, e a runtime deve expor apenas o minimo contrato operacional que continue necessario fora desse contexto. Ainda falta fechar, em decisao normativa, se esse "minimo contrato operacional" inclui algum resumo publico de banco ou se toda a superficie `bank.info` / `bank.slot_info` deve sair da ABI publica do guest. Esta agenda fica aceita com o seguinte fechamento de discussao: - debug e certificacao sao preocupacoes de host, nao do guest; - host desktop e o contexto principal para tooling de desenvolvimento, introspecao e emissao de certificados; - a runtime operacional nao deve carregar uma superficie geral de debug; - qualquer dado remanescente exposto pela runtime deve ser justificado como contrato operacional minimo e nao como conveniencia de tooling.