Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
3
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/discussion/workflow/decisions/DEC-0009-host-owned-debug-and-certification.md

4.7 KiB
Raw Blame History

id ticket title status created accepted agenda plans tags
DEC-0009 perf-runtime-introspection-syscalls Host-Owned Debug and Certification review 2026-04-18 AGD-0011
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.