---
id: PLN-0010
ticket: generic-memory-bank-slot-contract
title: PR/Plan - Asset Manager Bank Telemetry Slot Contract
status: in_progress
created: 2026-04-10
completed:
tags: [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.