---
id: AGD-0011
ticket: perf-runtime-introspection-syscalls
title: Agenda - [PERF] Runtime Introspection Syscalls
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---

# Agenda - [PERF] Runtime Introspection Syscalls

## Problema

As syscalls de introspecao ainda carregam custo de serializacao e agregacao demais para algo que deveria ser observabilidade sob demanda.

Hoje `BankInfo` e `BankSlotInfo` montam JSON por chamada e puxam dados potencialmente caros do asset manager.

## Dor

- 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.

## Hotspots Atuais

- [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)

## Alvo da Discussao

Separar claramente custo de introspecao/debug do custo da superficie operacional normal.

## O Que Precisa Ser Definido

1. Papel dessas syscalls.
   Decidir se `BankInfo`/`BankSlotInfo` sao:
   - superficie publica normal;
   - superficie de debug;
   - superficie host/devtools apenas.

2. Shape de retorno.
   Definir se JSON continua existindo ou se v1 exige shape mais barato/canonico.

3. Caching.
   Delimitar se snapshots de introspecao podem ser cacheados por frame.

4. Limites de uso.
   Decidir se o runtime deve impor throttling, budget ou feature gate de debug.

## Open Questions de Arquitetura

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?

## Dependencias

- `../specs/10-debug-inspection-and-profiling.md`
- `../specs/15-asset-management.md`
- `../specs/16-host-abi-and-syscalls.md`
- `../specs/16a-syscall-policies.md`

## Criterio de Saida Desta Agenda

Pode virar PR quando houver decisao escrita sobre:

- papel normativo de `BankInfo`/`BankSlotInfo`;
- permanencia ou remocao de JSON como shape de retorno;
- politica de cache/throttling;
- custo aceitavel de introspecao no dispatch.