---
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.