195 lines
10 KiB
Markdown
195 lines
10 KiB
Markdown
---
|
|
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.
|