126 lines
8.7 KiB
Markdown
126 lines
8.7 KiB
Markdown
---
|
|
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.
|