86 lines
4.4 KiB
Markdown
86 lines
4.4 KiB
Markdown
---
|
|
id: PLN-0031
|
|
ticket: perf-runtime-introspection-syscalls
|
|
title: DEC-0009 Runtime Bank ABI Cleanup
|
|
status: done
|
|
created: 2026-04-19
|
|
completed: 2026-04-19
|
|
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.
|