[PERF] Runtime Introspection Syscalls
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user