3.2 KiB
| id | ticket | title | created | tags | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
| LSN-0034 | perf-runtime-introspection-syscalls | Host-Owned Debug Boundaries and Cheap Machine Diagnostics | 2026-04-19 |
|
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.