Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
3
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/discussion/workflow/plans/PLN-0031-dec9-runtime-bank-abi-cleanup.md

4.4 KiB
Raw Blame History

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