prometeu-runtime/discussion/workflow/plans/PLN-0010-asset-manager-bank-telemetry-slot-contract.md

id	ticket	title	status	created	completed	tags
PLN-0010	generic-memory-bank-slot-contract	PR/Plan - Asset Manager Bank Telemetry Slot Contract	in_progress	2026-04-10		runtime asset memory-bank slots host telemetry certification

Briefing

Implement DEC-0012 by replacing the current byte-oriented bank telemetry path with a slot-first contract exposed directly by AssetManager. The execution MUST remove BankPolicy and BankStats from the visible telemetry path, keep canonical bank names aligned with BankType (GLYPH, SOUNDS), make the host overlay consume the new AssetManager summary, and migrate bank certification from byte limits to slot limits.

Decisions de Origem

• DEC-0012 - Asset Manager Bank Telemetry Slot Contract

Alvo

Deliver a canonical bank telemetry path with these properties:

• AssetManager exposes the visible per-bank summary.
• The visible summary shape is slot-first and limited to bank_type, used_slots, and total_slots.
• Detailed inspection remains slot-based through SlotRef / slot enums, not byte-based accounting.
• Host overlay and certification consume the new model.
• Legacy byte-oriented bank telemetry fields and limits are removed from the canonical path.

Escopo

Included

• Add a canonical BankTelemetry type to the shared HAL asset contract.
• Add an AssetBridge method for bank telemetry summaries exposed by AssetManager.
• Refactor AssetManager in crates/console/prometeu-drivers to compute slot-first bank telemetry.
• Remove BankStats from the visible bank telemetry path and stop using it for overlay and certification.
• Remove BankPolicy as the main modeling surface used to describe visible bank telemetry.
• Keep detailed slot inspection on explicit slot references instead of bank byte summaries.
• Update runtime telemetry / certification to track max_glyph_slots_used and max_sound_slots_used.
• Update host overlay consumers to render bank occupancy from the new AssetManager summary.
• Update runtime specs so the published contract describes slot-first bank telemetry and slot-based certification.

Fora de Escopo

• Reopening the base architectural decision about whether the visible summary belongs in AssetManager.
• Introducing new bank categories beyond the current GLYPH and SOUNDS.
• Reworking unrelated asset loading semantics, cartridge payload layout, or host UI design beyond adapting bank telemetry consumption.
• Removing all internal byte accounting if some private implementation detail still needs it temporarily.

Plano de Execucao

Step 1 - Lock the shared contract in HAL

What: Define the canonical shared types and trait surface for slot-first bank telemetry.

How: Add BankTelemetry to crates/console/prometeu-hal/src/asset.rs using bank_type, used_slots, and total_slots. Update crates/console/prometeu-hal/src/asset_bridge.rs so the visible bridge exposes a bank telemetry summary method from AssetManager. Remove or deprecate BankStats from the visible bridge path so downstream callers stop depending on byte-oriented bank summaries.

File(s):

• crates/console/prometeu-hal/src/asset.rs
• crates/console/prometeu-hal/src/asset_bridge.rs

Depends on:

• None

Step 2 - Refactor AssetManager to produce slot-first summaries

What: Move visible bank summary generation to a canonical AssetManager slot telemetry path.

How: Replace bank_info(BankType) -> BankStats with a summary path that reports only slot occupancy for each canonical bank type. Compute used_slots from the slot arrays already owned by AssetManager (gfx_slots, sound_slots) or equivalent canonical occupancy state. Keep detailed per-slot inspection in slot_info(SlotRef). Remove BankPolicy and its byte counters as the visible modeling surface for bank telemetry; if any internal storage helper remains temporarily, it must not leak into the shared contract.

File(s):

• crates/console/prometeu-drivers/src/asset.rs
• crates/console/prometeu-drivers/src/memory_banks.rs

Depends on:

• Step 1

Step 3 - Migrate runtime and host consumers to the new summary

What: Replace every bank summary consumer that still expects byte-oriented telemetry.

How: Update runtime and host callers to consume BankTelemetry from AssetManager instead of BankStats. Replace any direct bank_info(BankType) callsites with the new canonical summary path. Preserve slot-level inspection through slot_info(SlotRef) where detailed occupancy is needed. The host overlay must render bank occupancy from the AssetManager summary and must not reconstruct primary bank occupancy from bytes.

File(s):

• crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs
• crates/host/prometeu-host-desktop-winit/src/overlay.rs
• Any additional callsites found through rg 'bank_info|BankStats' crates

Depends on:

• Step 2

Step 4 - Replace certification byte limits with slot limits

What: Move bank certification from byte ceilings to slot ceilings.

How: Replace max_gfx_bytes and max_audio_bytes in telemetry / certification configuration and evaluation with slot-based limits such as max_glyph_slots_used and max_sound_slots_used. Update runtime accounting to record the maximum occupied slot count per bank during execution. Remove byte-limit evaluation from the bank certification path.

File(s):

• crates/console/prometeu-hal/src/telemetry.rs
• crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs

Depends on:

• Step 3

Step 5 - Remove residual canonical-path names and semantics that conflict with DEC-0012

What: Eliminate remaining visible-path terminology and structures that preserve the old model.

How: Ensure no visible bank telemetry path still uses GFX / AUD as canonical names, BankStats as the summary type, or byte fields as the public bank occupancy contract. Keep GLYPH and SOUNDS aligned with the existing BankType enum. If bridges, docs, or helper APIs still expose the old path, remove or rename them in the same change set so the canonical path is unambiguous.

File(s):

• crates/console/prometeu-hal/src/asset.rs
• crates/console/prometeu-hal/src/asset_bridge.rs
• crates/console/prometeu-drivers/src/asset.rs
• crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs
• crates/host/prometeu-host-desktop-winit/src/overlay.rs

Depends on:

• Step 4

Step 6 - Update published specifications

What: Align canonical docs with the implemented slot-first bank contract.

How: Update runtime specs to state that bank telemetry is exposed from AssetManager, that the published per-bank summary is slot-first, that detailed occupancy inspection remains slot-based, and that certification uses slot ceilings instead of byte ceilings. Remove residual published references to max_gfx_bytes, max_audio_bytes, or byte-oriented bank summaries in canonical specs.

File(s):

• docs/specs/runtime/15-asset-management.md
• docs/specs/runtime/10-debug-inspection-and-profiling.md
• Any additional runtime spec file that still documents byte-based bank certification or overlay bank summary consumption

Depends on:

• Step 5

Criterios de Aceite

• AssetManager is the canonical visible source of bank telemetry.
• The visible bank summary contract uses only bank_type, used_slots, and total_slots.
• Canonical bank names in the visible contract are GLYPH and SOUNDS.
• BankStats is no longer used as the visible bank telemetry summary type.
• BankPolicy is not the main visible modeling surface for bank telemetry.
• Host overlay bank occupancy uses the new AssetManager bank summary.
• Detailed occupancy inspection remains slot-based via slot references or equivalent slot enums.
• max_gfx_bytes and max_audio_bytes are removed from bank certification.
• Slot-based bank certification limits exist and are enforced.
• Published runtime specs describe the slot-first contract and slot-based certification model.

Tests / Validacao

Unit Tests

• Add or update tests in crates/console/prometeu-drivers/src/asset.rs to verify the bank summary reports correct used_slots and total_slots for GLYPH and SOUNDS.
• Add or update tests in crates/console/prometeu-hal/src/telemetry.rs to verify slot-based certification thresholds trigger correctly and byte-based limits no longer exist in the bank path.
• Keep slot inspection tests proving slot_info(SlotRef) remains the detailed inspection mechanism.

Integration Tests

• Run cargo test -p prometeu-drivers.
• Run cargo test -p prometeu-hal.
• Run cargo test -p prometeu-system.
• Run cargo test -p prometeu-host-desktop-winit if overlay bank telemetry callsites are changed there.
• Run cargo check for the full touched workspace if cross-crate API changes make targeted tests insufficient.

Manual Verification

• Start the desktop host and confirm the overlay shows per-bank occupancy using slot counts, not bytes.
• Confirm the overlay labels use GLYPH and SOUNDS or approved presentation labels derived from those canonical bank types.
• Confirm certification output reports slot-limit violations and no longer reports max_gfx_bytes / max_audio_bytes.
• Confirm detailed slot inspection still works for both glyph and sound slots.

Dependencies

• DEC-0012 remains accepted and unchanged.
• Existing BankType enum values remain GLYPH and SOUNDS.
• AssetManager remains the asset-domain owner for slot occupancy summaries.

Riscos

• Cross-crate trait changes in AssetBridge may create a wider refactor than the bank telemetry callsites initially suggest.
• Removing BankStats from the visible path may expose hidden byte-based assumptions in runtime telemetry, overlay formatting, or tests.
• Certification migration may fail partially if slot maxima are recorded in one layer while enforcement still reads old byte fields in another layer.
• If byte accounting is still needed internally during the refactor, the implementation can accidentally leak that detail back into public interfaces unless the change set is kept cohesive.