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