[PERF] Runtime Introspection Syscalls
This commit is contained in:
@@ -2,19 +2,19 @@
|
||||
id: DEC-0009
|
||||
ticket: perf-runtime-introspection-syscalls
|
||||
title: Host-Owned Debug and Certification
|
||||
status: review
|
||||
status: accepted
|
||||
created: 2026-04-18
|
||||
accepted:
|
||||
accepted: 2026-04-19
|
||||
agenda: AGD-0011
|
||||
plans: []
|
||||
plans: [PLN-0030, PLN-0031, PLN-0032]
|
||||
tags: [perf, runtime, host, debug, certification, syscall, telemetry]
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
Review
|
||||
Accepted
|
||||
|
||||
Normative draft derived from `AGD-0011`. It is intended to lock the boundary between runtime operational surface and host-owned development tooling.
|
||||
Accepted normative decision derived from `AGD-0011`. It locks the boundary between runtime operational surface and host-owned development tooling.
|
||||
|
||||
## Contexto
|
||||
|
||||
@@ -96,3 +96,4 @@ The decision also aligns the runtime with prior convergence already visible in t
|
||||
## Revision Log
|
||||
|
||||
- 2026-04-18: Initial draft from AGD-0011.
|
||||
- 2026-04-19: Accepted and decomposed into `PLN-0030`, `PLN-0031`, and `PLN-0032`.
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
id: PLN-0030
|
||||
ticket: perf-runtime-introspection-syscalls
|
||||
title: DEC-0009 Spec Boundary Propagation
|
||||
status: done
|
||||
created: 2026-04-19
|
||||
completed: 2026-04-19
|
||||
tags: [runtime, spec, host, debug, certification, syscall]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Propagate `DEC-0009` into the canonical runtime specifications so that debug tooling and certification are described as host-owned concerns, not guest/runtime feature surfaces.
|
||||
|
||||
## Decisions de Origem
|
||||
|
||||
- `DEC-0009` - Host-Owned Debug and Certification
|
||||
|
||||
## Alvo
|
||||
|
||||
Lock the written contract across the runtime specs before code execution starts, so implementation work does not reopen the architecture.
|
||||
|
||||
## Escopo
|
||||
|
||||
- update `docs/specs/runtime/10-debug-inspection-and-profiling.md` to narrow the runtime-visible diagnostics surface and state explicitly that detailed inspection and certification output are host-owned;
|
||||
- update `docs/specs/runtime/15-asset-management.md` to keep bank telemetry slot-first and prohibit guest-visible debug-oriented bank inspection as a general ABI;
|
||||
- update `docs/specs/runtime/16-host-abi-and-syscalls.md` so `bank.info` / `bank.slot_info` are either removed from the public syscall catalog or redefined only as bounded operational ABI;
|
||||
- update `docs/specs/runtime/16a-syscall-policies.md` to reinforce that debug convenience APIs are not valid justification for guest-visible syscalls;
|
||||
- align cross-references to existing host-overlay and telemetry chapters where they already define the canonical diagnostics pipeline.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- changing Rust code in `crates/`;
|
||||
- introducing a new guest-facing inspection ABI;
|
||||
- redesigning debugger transport or host protocol payload schemas.
|
||||
|
||||
## Plano de Execucao
|
||||
|
||||
### Step 1 - Rewrite the normative ownership language
|
||||
|
||||
**What:** Rewrite the affected spec chapters so that debug tooling, rich inspection, and certification reporting are host-owned responsibilities.
|
||||
**How:** Replace guest/runtime-centric wording in `10-debug-inspection-and-profiling.md` with host-owned framing, keeping runtime obligations limited to bounded telemetry production and deterministic machine behavior.
|
||||
**File(s):** `docs/specs/runtime/10-debug-inspection-and-profiling.md`
|
||||
|
||||
### Step 2 - Converge the asset/bank contract
|
||||
|
||||
**What:** Align asset-management language with the decision that slot-first telemetry is the visible contract and bank inspection is not a general guest debug service.
|
||||
**How:** Update the bank telemetry and diagnostics sections to describe the canonical operational summary, the absence of JSON textual bank ABI, and the host ownership of detailed slot inspection.
|
||||
**File(s):** `docs/specs/runtime/15-asset-management.md`
|
||||
|
||||
### Step 3 - Tighten the syscall chapter
|
||||
|
||||
**What:** Remove ambiguity around `bank.info` and `bank.slot_info` in the public ABI contract.
|
||||
**How:** Amend the host ABI and syscall policy chapters so they either remove those calls from the public surface or constrain any surviving `bank.info` form to a cheap, deterministic, non-JSON operational summary justified by machine needs.
|
||||
**File(s):** `docs/specs/runtime/16-host-abi-and-syscalls.md`, `docs/specs/runtime/16a-syscall-policies.md`
|
||||
|
||||
### Step 4 - Verify cross-chapter consistency
|
||||
|
||||
**What:** Ensure no remaining chapter describes certification or debug tooling as runtime-owned functionality.
|
||||
**How:** Review cross-references in nearby runtime chapters that mention certification, host tooling, or diagnostics and patch inconsistent wording where directly impacted by the edited contract.
|
||||
**File(s):** `docs/specs/runtime/09-events-and-concurrency.md`, `docs/specs/runtime/11-portability-and-cross-platform-execution.md`, plus the edited primary chapters
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- `DEC-0009` is cited explicitly in the updated spec material.
|
||||
- The specs state unambiguously that certification generation is host-owned.
|
||||
- The specs no longer describe JSON-formatted bank inspection as part of the long-term public guest ABI.
|
||||
- The public runtime contract for bank telemetry remains slot-first and bounded.
|
||||
- The updated text is internally consistent across the touched runtime chapters.
|
||||
|
||||
## Tests / Validacao
|
||||
|
||||
- manual doc review of the edited chapters for contradictory wording about ownership;
|
||||
- targeted search for `bank.info`, `bank.slot_info`, `certification`, and `debug` in `docs/specs/runtime/` to ensure the remaining text matches `DEC-0009`;
|
||||
- verify that all new or changed published spec text remains in English.
|
||||
|
||||
## Riscos
|
||||
|
||||
- spec-only propagation may accidentally leave residual guest-oriented language that later reintroduces ABI ambiguity;
|
||||
- over-editing adjacent chapters could broaden the scope beyond `DEC-0009`;
|
||||
- under-specifying the surviving `bank.info` option could block the runtime ABI cleanup plan.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `DEC-0009` must remain accepted and unchanged while this plan is executed.
|
||||
- This plan should complete before runtime syscall removal or narrowing work begins.
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
id: PLN-0031
|
||||
ticket: perf-runtime-introspection-syscalls
|
||||
title: DEC-0009 Runtime Bank ABI Cleanup
|
||||
status: review
|
||||
created: 2026-04-19
|
||||
completed:
|
||||
tags: [runtime, syscall, abi, bank, telemetry, debug]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Execute the runtime-side ABI cleanup mandated by `DEC-0009` by removing or narrowing guest-visible bank inspection syscalls and eliminating JSON formatting from dispatch.
|
||||
|
||||
## Decisions de Origem
|
||||
|
||||
- `DEC-0009` - Host-Owned Debug and Certification
|
||||
|
||||
## Alvo
|
||||
|
||||
Bring the public runtime syscall surface into compliance with the accepted decision while preserving any truly necessary cheap operational summary.
|
||||
|
||||
## Escopo
|
||||
|
||||
- review and update the public bank syscall registry in `crates/console/prometeu-hal/src/syscalls/domains/bank.rs`;
|
||||
- refactor bank syscall dispatch in `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`;
|
||||
- align runtime tests around the new ABI shape and the removal of JSON string payloads;
|
||||
- keep internal asset telemetry and `slot_info` helpers available for host/runtime internals where they are still needed.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- changing the desktop debugger protocol payloads;
|
||||
- introducing a new host transport;
|
||||
- modifying unrelated asset loading semantics or slot ownership rules.
|
||||
|
||||
## Plano de Execucao
|
||||
|
||||
### Step 1 - Decide the surviving machine-facing bank surface
|
||||
|
||||
**What:** Resolve the exact runtime-facing outcome for `bank.info` and `bank.slot_info` under the accepted decision.
|
||||
**How:** Use the accepted spec text from `PLN-0030` as the source of truth and implement one of two bounded outcomes: remove both public syscalls, or keep only a cheap non-JSON `bank.info` summary if an operational use case remains documented.
|
||||
**File(s):** `docs/specs/runtime/16-host-abi-and-syscalls.md`, `crates/console/prometeu-hal/src/syscalls/domains/bank.rs`
|
||||
|
||||
### Step 2 - Remove JSON-on-the-wire dispatch behavior
|
||||
|
||||
**What:** Eliminate textual JSON serialization from the runtime dispatch path.
|
||||
**How:** Delete the `serde_json::to_string` bank inspection branches in `virtual_machine_runtime/dispatch.rs` and replace them with the chosen bounded ABI behavior from Step 1.
|
||||
**File(s):** `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`
|
||||
|
||||
### Step 3 - Realign tests and syscall metadata
|
||||
|
||||
**What:** Update test coverage and metadata assumptions to the new bank syscall contract.
|
||||
**How:** Add or update tests for registry shape, return-slot behavior, and fault/status behavior so the runtime proves that debug-only bank inspection no longer leaks through the guest ABI.
|
||||
**File(s):** `crates/console/prometeu-hal/src/syscalls/domains/bank.rs`, `crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs`, any syscall metadata tests discovered during execution
|
||||
|
||||
### Step 4 - Preserve internal host-facing inspection sources
|
||||
|
||||
**What:** Keep slot and bank telemetry available for host-owned tooling without re-exporting them as guest ABI.
|
||||
**How:** Verify that `AssetManager` telemetry helpers and internal `slot_info` access remain usable by host/runtime internals after the public syscall cleanup.
|
||||
**File(s):** `crates/console/prometeu-drivers/src/asset.rs`, related internal callers discovered during execution
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- The public bank syscall registry no longer exposes JSON-formatted debug inspection.
|
||||
- `virtual_machine_runtime/dispatch.rs` no longer serializes bank telemetry or slot details into JSON strings for guest return values.
|
||||
- Any surviving `bank.info` surface is cheap, deterministic, bounded, and documented as operational ABI.
|
||||
- Guest code cannot access detailed slot inspection through a generic debug convenience syscall.
|
||||
- Runtime tests cover the new ABI behavior.
|
||||
|
||||
## Tests / Validacao
|
||||
|
||||
- unit tests for syscall registry metadata and runtime dispatch behavior;
|
||||
- targeted search for `serde_json::to_string`, `BankInfo`, and `BankSlotInfo` in the runtime crates after the refactor;
|
||||
- run the affected Rust test suites for HAL/system crates that cover syscall dispatch and bank telemetry behavior.
|
||||
|
||||
## Riscos
|
||||
|
||||
- removing syscalls without finishing spec propagation first may create contract drift;
|
||||
- keeping a reduced `bank.info` without a crisp return shape may preserve ambiguity;
|
||||
- internal host tooling might still rely on code paths that currently sit behind the guest syscall implementation.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `PLN-0030` should land first or in lockstep so the code change follows published contract text.
|
||||
- Host tooling migration work in `PLN-0032` may depend on internal inspection helpers preserved by this plan.
|
||||
@@ -0,0 +1,84 @@
|
||||
---
|
||||
id: PLN-0032
|
||||
ticket: perf-runtime-introspection-syscalls
|
||||
title: DEC-0009 Host Debugger and Certification Alignment
|
||||
status: review
|
||||
created: 2026-04-19
|
||||
completed:
|
||||
tags: [host, debug, certification, telemetry, desktop]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Align the desktop host debugger and certification pipeline with `DEC-0009` so detailed inspection and certification outputs are consumed from host-owned telemetry/debug flows rather than from guest-visible runtime APIs.
|
||||
|
||||
## Decisions de Origem
|
||||
|
||||
- `DEC-0009` - Host-Owned Debug and Certification
|
||||
|
||||
## Alvo
|
||||
|
||||
Make the desktop host the canonical consumer of runtime telemetry, certification configuration, and detailed inspection data after the guest ABI cleanup.
|
||||
|
||||
## Escopo
|
||||
|
||||
- review `crates/host/prometeu-host-desktop-winit/src/debugger.rs` for reliance on guest-facing inspection assumptions and document the intended host-owned data sources;
|
||||
- review `crates/host/prometeu-host-desktop-winit/src/cap.rs` and certification wiring in `runner.rs` so certification remains fully host-generated;
|
||||
- align any host-side contracts with the accepted spec and runtime ABI cleanup;
|
||||
- add or update tests that prove certification/debug behavior does not depend on guest-visible debug syscalls.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- redesigning the external debugger client application;
|
||||
- changing unrelated desktop rendering or overlay presentation behavior;
|
||||
- adding new certification metrics beyond what existing telemetry already supports.
|
||||
|
||||
## Plano de Execucao
|
||||
|
||||
### Step 1 - Audit host data sources
|
||||
|
||||
**What:** Identify where the desktop host already consumes telemetry and where it still implicitly depends on guest-oriented inspection concepts.
|
||||
**How:** Review `debugger.rs`, `runner.rs`, and supporting modules for state, telemetry, certification, and inspection flows; record which inputs come from atomic telemetry, crash reports, or direct host/runtime internals.
|
||||
**File(s):** `crates/host/prometeu-host-desktop-winit/src/debugger.rs`, `crates/host/prometeu-host-desktop-winit/src/runner.rs`, `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
|
||||
|
||||
### Step 2 - Lock certification ownership in host code
|
||||
|
||||
**What:** Ensure certification remains generated and configured exclusively in the host layer.
|
||||
**How:** Update certification setup and any related documentation/comments so host code owns report generation and consumes runtime telemetry snapshots rather than guest-facing diagnostic APIs.
|
||||
**File(s):** `crates/host/prometeu-host-desktop-winit/src/cap.rs`, `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
||||
|
||||
### Step 3 - Adjust debugger integration after ABI cleanup
|
||||
|
||||
**What:** Keep rich inspection available to developer tooling after `PLN-0031` removes or narrows guest bank inspection syscalls.
|
||||
**How:** Move any remaining detailed inspection dependence onto host-owned runtime access paths or protocol messages that do not reintroduce guest ABI surface.
|
||||
**File(s):** `crates/host/prometeu-host-desktop-winit/src/debugger.rs`, related protocol or host integration files discovered during execution
|
||||
|
||||
### Step 4 - Prove the boundary in tests
|
||||
|
||||
**What:** Add evidence that host tooling and certification still work without guest-visible debug syscalls.
|
||||
**How:** Extend host tests around debugger startup, telemetry streaming, and certification config loading, and add focused assertions that the host path depends on telemetry/internal access rather than guest ABI inspection.
|
||||
**File(s):** `crates/host/prometeu-host-desktop-winit/src/debugger.rs`, `crates/host/prometeu-host-desktop-winit/src/runner.rs`, `crates/host/prometeu-host-desktop-winit/src/cap.rs`
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- The host debugger and certification pipeline are described and implemented as host-owned consumers.
|
||||
- No host feature requires `bank.slot_info` or JSON `bank.info` to remain exposed to guest code.
|
||||
- Certification configuration and report generation stay in host code.
|
||||
- Host-side tests cover the intended telemetry/debug/certification path after ABI cleanup.
|
||||
|
||||
## Tests / Validacao
|
||||
|
||||
- run host crate tests covering debugger startup, command handling, and certification config loading;
|
||||
- targeted search in the host crate for references to guest-visible bank inspection APIs after implementation;
|
||||
- manual review that host comments and module responsibilities match `DEC-0009`.
|
||||
|
||||
## Riscos
|
||||
|
||||
- host code may still rely on implicit runtime internals that are not clearly documented;
|
||||
- coupling host tooling migration to runtime ABI cleanup could stall both if sequencing is unclear;
|
||||
- lack of explicit host-side test coverage may hide regressions until manual debugger use.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `PLN-0030` provides the published ownership model.
|
||||
- `PLN-0031` defines the final runtime ABI boundary that host tooling must stop depending on.
|
||||
Reference in New Issue
Block a user