Intrepid/prometeu-runtime

Fork 0

bQUARKz e895b01b8f

[PERF] Runtime Introspection Syscalls

2026-04-18 18:19:39 +01:00

8.7 KiB

Raw Blame History

ticket

title

status

created

resolved

decision

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.

8.7 KiB Raw Blame History