prometeu-runtime/discussion/workflow/plans/PLN-0031-dec9-runtime-bank-abi-cleanup.md

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