[PERF] Runtime Introspection Syscalls
This commit is contained in:
parent
509b669db5
commit
e895b01b8f
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -1,4 +1,4 @@
|
||||
{"type":"meta","next_id":{"DSC":29,"AGD":29,"DEC":17,"PLN":30,"LSN":34,"CLSN":1}}
|
||||
{"type":"meta","next_id":{"DSC":29,"AGD":29,"DEC":18,"PLN":30,"LSN":34,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["perf","runtime","telemetry"],"agendas":[{"id":"AGD-0021","file":"workflow/agendas/AGD-0021-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0008","file":"workflow/decisions/DEC-0008-full-migration-to-atomic-telemetry.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0007","file":"workflow/plans/PLN-0007-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0028","file":"lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"workflow/decisions/DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"workflow/plans/PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
|
||||
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
|
||||
@ -14,7 +14,7 @@
|
||||
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0008","file":"workflow/agendas/AGD-0008-perf-async-background-work-lanes-for-assets-and-fs.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0010","status":"open","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0009","file":"workflow/agendas/AGD-0009-perf-host-desktop-frame-pacing-and-presentation.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0011","status":"open","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0010","file":"workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0012","status":"open","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0012","status":"review","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-04-18","tags":["perf","runtime","syscall","telemetry","debug","asset"],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-04-18"}],"decisions":[{"id":"DEC-0009","file":"workflow/decisions/DEC-0009-host-owned-debug-and-certification.md","status":"review","created_at":"2026-04-18","updated_at":"2026-04-18","ref_agenda":"AGD-0011"}],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"perf-host-debug-overlay-isolation","title":"Agenda - [PERF] Host Debug Overlay Isolation","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"lessons/DSC-0013-perf-host-debug-overlay-isolation/LSN-0027-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
{"type":"discussion","id":"DSC-0024","status":"done","ticket":"generic-memory-bank-slot-contract","title":"Agenda - Generic Memory Bank Slot Contract","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["runtime","asset","memory-bank","slots","host"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"lessons/DSC-0024-generic-memory-bank-slot-contract/LSN-0029-slot-first-bank-telemetry-belongs-in-asset-manager.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
{"type":"discussion","id":"DSC-0025","status":"done","ticket":"scene-bank-and-viewport-cache-refactor","title":"Scene Bank and Viewport Cache Refactor","created_at":"2026-04-11","updated_at":"2026-04-14","tags":["gfx","tilemap","runtime","render"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"lessons/DSC-0025-scene-bank-and-viewport-cache-refactor/LSN-0030-canonical-scene-cache-and-resolver-split.md","status":"done","created_at":"2026-04-14","updated_at":"2026-04-14"}]}
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -0,0 +1,98 @@
|
||||
---
|
||||
id: DEC-0009
|
||||
ticket: perf-runtime-introspection-syscalls
|
||||
title: Host-Owned Debug and Certification
|
||||
status: review
|
||||
created: 2026-04-18
|
||||
accepted:
|
||||
agenda: AGD-0011
|
||||
plans: []
|
||||
tags: [perf, runtime, host, debug, certification, syscall, telemetry]
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
Review
|
||||
|
||||
Normative draft derived from `AGD-0011`. It is intended to lock the boundary between runtime operational surface and host-owned development tooling.
|
||||
|
||||
## Contexto
|
||||
|
||||
The current runtime still exposes bank introspection syscalls that serialize JSON strings during dispatch. In parallel, the repository already converged on host-side debug overlay, atomic telemetry snapshots, and slot-first bank telemetry semantics.
|
||||
|
||||
The remaining ambiguity was whether debug and certification should continue to exist as guest-visible runtime concerns or be treated as host responsibilities.
|
||||
|
||||
This discussion is now closed at the architectural level: development diagnostics are host concerns, not guest concerns.
|
||||
|
||||
## Decisao
|
||||
|
||||
PROMETEU debug tooling and certification SHALL be host-owned concerns.
|
||||
|
||||
Normative consequences:
|
||||
|
||||
- the guest/runtime public operational contract MUST NOT include a general-purpose debug surface;
|
||||
- certification MUST NOT be modeled as a guest-visible runtime feature;
|
||||
- the desktop host SHALL be the primary environment for debug tooling, inspection, telemetry consumption, and certification output;
|
||||
- the runtime MAY expose only the minimum machine-facing operational data that remains necessary outside host tooling;
|
||||
- any remaining runtime-visible diagnostics MUST be justified as operational contract, not as generic debug convenience.
|
||||
|
||||
For the bank introspection topic specifically:
|
||||
|
||||
- `bank.slot_info` SHALL be treated as host/debug tooling surface and SHOULD NOT remain part of the general guest ABI;
|
||||
- `bank.info` MUST NOT remain a JSON textual contract if it survives in any public form;
|
||||
- if a public `bank.info` remains, it MUST be reduced to a canonical cheap operational summary aligned with the slot-first bank telemetry model;
|
||||
- if no such operational need exists, `bank.info` SHOULD also leave the guest ABI.
|
||||
|
||||
## Rationale
|
||||
|
||||
This decision follows directly from the product reality of the platform:
|
||||
|
||||
- end users on real handheld/runtime targets do not inspect debug data or certification reports;
|
||||
- game development, jams, profiling, debugging, and certification analysis occur on PC/desktop;
|
||||
- keeping debug and certification inside the guest/runtime surface makes production execution pay for tooling-oriented concerns;
|
||||
- treating certification as a consumer of host-side debug/telemetry output keeps one diagnostic pipeline instead of duplicating machine and host responsibilities.
|
||||
|
||||
The decision also aligns the runtime with prior convergence already visible in the repository:
|
||||
|
||||
- host overlay lives outside the emulated framebuffer and outside the machine contract;
|
||||
- telemetry is already snapshot-oriented and host-consumable;
|
||||
- public bank telemetry semantics are already slot-first and narrower than arbitrary textual inspection payloads.
|
||||
|
||||
## Invariantes / Contrato
|
||||
|
||||
- Runtime operational behavior MUST remain independent from whether host debug tooling is active.
|
||||
- Runtime production targets MUST NOT require debug surfaces to operate correctly.
|
||||
- Certification generation MUST happen in the host layer.
|
||||
- Host certification MAY consume the same telemetry/debug pipeline used for tooling and inspection.
|
||||
- Runtime-visible diagnostics, if any remain, MUST be explicitly documented as operational ABI and MUST have bounded cost.
|
||||
- JSON-on-the-wire debug payloads MUST NOT define the long-term public ABI.
|
||||
|
||||
## Impactos
|
||||
|
||||
- Specs must be updated so that debug and certification are described as host-owned concerns rather than guest/runtime features.
|
||||
- The syscall surface must be reviewed to remove, restrict, or redesign `bank.info` and `bank.slot_info`.
|
||||
- The host debugger/certification path becomes the canonical consumer of detailed inspection output.
|
||||
- Any runtime code that formats debug payloads textually in dispatch becomes suspect and should be removed or reduced.
|
||||
- Future plans must not reintroduce guest-facing debug APIs without a new explicit decision.
|
||||
|
||||
## Referencias
|
||||
|
||||
- `AGD-0011`
|
||||
- `docs/specs/runtime/10-debug-inspection-and-profiling.md`
|
||||
- `docs/specs/runtime/15-asset-management.md`
|
||||
- `docs/specs/runtime/16-host-abi-and-syscalls.md`
|
||||
- `docs/specs/runtime/16a-syscall-policies.md`
|
||||
- `LSN-0026`
|
||||
- `LSN-0027`
|
||||
- `LSN-0029`
|
||||
|
||||
## Propagacao Necessaria
|
||||
|
||||
- Update runtime specs to move certification ownership to the host layer.
|
||||
- Update runtime specs to narrow or remove guest-visible debug framing.
|
||||
- Write an execution plan for syscall/spec/host propagation before implementation.
|
||||
- Review runtime dispatch for `bank.info` / `bank.slot_info` and align the ABI with this boundary.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-04-18: Initial draft from AGD-0011.
|
||||
Loading…
x
Reference in New Issue
Block a user