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	open	2026-04-10		runtime asset memory-bank slots host telemetry

Objective

Implement the DEC-0012 bank telemetry contract so AssetManager exposes slot-based bank summaries using canonical bank names GLYPH and SOUND, while host overlay and certification consume slot-based limits instead of byte-based bank metrics.

Background

DEC-0012 locked the bank telemetry contract around a simple slot-first structure:

pub struct BankTelemetry {
    pub bank_type: BankType,
    pub used_slots: usize,
    pub total_slots: usize,
}

This replaces the old bank telemetry path that relied on byte-oriented structures and presentation aliases. The implementation must remove BankPolicy and BankStats from the exposed bank telemetry contract path, move visible bank summaries to AssetManager, and migrate certification rules from byte-based thresholds to slot-based thresholds.

Scope

Included

• Add a visible slot-based BankTelemetry contract owned by AssetManager.
• Remove BankStats from the public bank telemetry contract path.
• Remove BankPolicy from the bank telemetry contract path and refactor internal code accordingly.
• Update bridge/consumer APIs so bank summaries come from AssetManager slot telemetry.
• Migrate certification from max_gfx_bytes / max_audio_bytes to slot-based limits for GLYPH and SOUND.
• Update host overlay to iterate AssetManager bank telemetry using canonical GLYPH and SOUND labels.
• Update specs/docs affected by the contract change.

Excluded

• Adding new bank kinds beyond the currently supported GLYPH and SOUND.
• Reworking unrelated asset load/commit semantics.
• Redesigning generic slot-detail payloads beyond the accepted summary shape unless implementation requires a narrowly scoped helper.

Execution Steps

Step 1 - Introduce BankTelemetry in the exposed asset contract

What: Define the new slot-based summary type and make it the canonical visible representation of bank telemetry.

How: Add BankTelemetry to the HAL asset domain and ensure canonical naming uses GLYPH and SOUND. Remove or deprecate exposed BankStats paths that conflict with the new contract.

File(s):

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

Step 2 - Make AssetManager expose bank telemetry directly

What: Implement AssetManager support for returning Vec<BankTelemetry> from live slot occupancy.

How: Compute used_slots from current slot occupancy and total_slots from the fixed slot arrays for GLYPH and SOUND. Keep implementation simple and derive the summary directly from the installed slots. Refactor any existing public bank-info consumers away from byte-oriented APIs.

File(s):

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

Step 3 - Remove byte-based bank certification rules

What: Replace byte-based certification limits for banks with slot-based limits.

How: Remove max_gfx_bytes and max_audio_bytes from certification config and certifier checks. Introduce slot-based limits such as max_glyph_slots_used and max_sound_slots_used, and evaluate them against BankTelemetry summaries or equivalent slot-based data available at frame-end.

File(s):

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

Step 4 - Update host overlay to consume slot telemetry

What: Replace hardcoded bank presentation with iteration over AssetManager bank telemetry.

How: Render one bar per bank using bank_type, used_slots, and total_slots. Use canonical labels GLYPH and SOUND, and remove any byte-based bank presentation from the overlay.

File(s):

• crates/host/prometeu-host-desktop-winit/src/overlay.rs
• Any host-side adapter/helper used to access asset telemetry

Step 5 - Remove obsolete structures from the contract path

What: Eliminate BankPolicy and BankStats from the exposed bank telemetry path.

How: Refactor code so the new slot-based path is the only public contract. If internal implementation helpers must remain temporarily during migration, keep them private and make sure no consumer depends on them as contract.

File(s):

• crates/console/prometeu-drivers/src/asset.rs
• crates/console/prometeu-hal/src/asset.rs
• Related callers revealed during implementation

Step 6 - Update normative documentation

What: Align specifications with the new slot-based bank telemetry contract.

How: Update relevant runtime documentation to describe bank occupancy in terms of GLYPH and SOUND slot usage, and remove outdated references to byte-based bank telemetry where they were treated as visible contract.

File(s):

• docs/specs/runtime/10-debug-inspection-and-profiling.md
• docs/specs/runtime/15-asset-management.md
• Any additional touched runtime spec chapter

Test Requirements

Unit Tests

• AssetManager reports correct BankTelemetry for empty and occupied GLYPH / SOUND slots.
• Certification slot limits trigger correctly for GLYPH and SOUND.
• Overlay rendering accepts generic bank telemetry iteration.

Integration Tests

• cargo check for affected HAL, drivers, system, and host crates.
• Focused tests for asset bank telemetry and certification migration.

Manual Verification

• Run the desktop host and confirm banks appear as GLYPH and SOUND.
• Confirm bank bars track occupied slots instead of bytes.
• Confirm certification behavior still reports bank pressure using slot limits.

Acceptance Criteria

• AssetManager exposes a visible BankTelemetry summary with bank_type, used_slots, and total_slots.
• Canonical bank names in the new contract are GLYPH and SOUND.
• Byte-based bank certification limits are removed and replaced by slot-based limits.
• Host overlay renders bank occupancy from generic slot telemetry rather than byte-oriented hardcoded bank logic.
• BankPolicy and BankStats are no longer part of the exposed bank telemetry contract path.

Dependencies

• DEC-0012 accepted and unchanged.

Risks

• Removing byte-based bank paths may have wider ripple effects than expected if old APIs are reused outside the overlay.
• The line between “removed from contract path” and “removed completely from implementation” must stay explicit during refactor to avoid accidental partial migration.
• Certification migration must stay synchronized with telemetry migration or the host and certifier will diverge semantically.