---
id: DEC-0009
ticket: perf-runtime-introspection-syscalls
title: Host-Owned Debug and Certification
status: accepted
created: 2026-04-18
accepted: 2026-04-19
agenda: AGD-0011
plans: [PLN-0030, PLN-0031, PLN-0032]
tags: [perf, runtime, host, debug, certification, syscall, telemetry]
---

## Status

Accepted

Accepted normative decision derived from `AGD-0011`. It locks 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.
- 2026-04-19: Accepted and decomposed into `PLN-0030`, `PLN-0031`, and `PLN-0032`.