56 lines
3.2 KiB
Markdown
56 lines
3.2 KiB
Markdown
---
|
|
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.
|