100 lines
4.9 KiB
Markdown
100 lines
4.9 KiB
Markdown
---
|
|
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`.
|