---
id: LSN-0034
ticket: perf-runtime-introspection-syscalls
title: Host-Owned Debug Boundaries and Cheap Machine Diagnostics
created: 2026-04-19
tags: [runtime, host, debug, certification, telemetry, abi]
---

## Context

`DSC-0012` resolved a recurring ambiguity in PROMETEU: whether development diagnostics should be treated as part of the guest/runtime contract or as host tooling concerns. The codebase already had host overlay rendering, atomic telemetry snapshots, and slot-first bank telemetry, but the runtime still exposed JSON-formatted bank inspection syscalls.

The completed work converged specs, runtime ABI, and host debugger behavior around a single boundary: rich diagnostics belong to the host, while the runtime exports only bounded machine-facing summaries.

## Key Decisions

### Host-Owned Debug and Certification (`DEC-0009`)

**What:**
Debug tooling and certification are host-owned concerns. Guest-visible debug convenience APIs are not part of the long-term runtime ABI.

**Why:**
Development inspection, profiling, and certification analysis happen on desktop host environments, not on production handheld/runtime targets. Keeping those concerns in the guest ABI forces production execution to carry tooling-oriented surface area and cost.

**Trade-offs:**
The runtime gives up general introspection syscalls, so host tooling must consume telemetry and internal host/runtime integration points directly. In exchange, the public ABI becomes cheaper, narrower, and easier to reason about.

## Patterns and Algorithms

- Treat diagnostics as a layered boundary:
  The runtime owns deterministic counters, bounded summaries, and machine-facing operational signals.
  The host owns rendering, protocol projection, certification output, and rich inspection UX.

- Prefer cheap structured values over textual debug payloads:
  If a machine-facing diagnostic survives, it should return small canonical stack values such as `(used_slots, total_slots)`, not JSON blobs.

- Use one telemetry source for all host consumers:
  Atomic telemetry snapshots should feed debugger streaming, overlays, and certification evaluation so the platform does not fork multiple diagnostic pipelines.

- Keep telemetry slot-first when the real machine contract is slot-first:
  Bank occupancy was correctly modeled as slot usage, so the surviving public summary stayed aligned with that semantic model instead of byte-oriented totals or slot-detail dumps.

## Pitfalls

- Do not let host-only needs backdoor themselves into the guest ABI as "temporary" debug syscalls. They tend to linger and become accidental contract.

- Do not use JSON-on-the-wire as a fallback ABI for runtime inspection. It is easy to add, but it creates unbounded cost and weakens the canonical machine model.

- Do not update only specs or only code. This boundary needed spec propagation, runtime ABI cleanup, and host debugger alignment together to avoid split-brain behavior.

## Takeaways

- Debug and certification pipelines should be modeled as host products that consume runtime telemetry, not as guest features.
- Surviving machine diagnostics must be justified by operational need and expressed as bounded structured values.
- The clean boundary is: runtime produces telemetry, host interprets and presents it.