71 lines
4.0 KiB
Markdown
71 lines
4.0 KiB
Markdown
---
|
|
id: LSN-0029
|
|
ticket: generic-memory-bank-slot-contract
|
|
title: Slot-First Bank Telemetry Belongs in AssetManager
|
|
created: 2026-04-10
|
|
tags: [runtime, asset, telemetry, memory-bank, slots]
|
|
---
|
|
|
|
## Context
|
|
|
|
This discussion started from a mismatch between how memory banks were modeled and how engineers actually reason about them in the runtime. The public-facing bank path still leaned on byte totals and helper structures such as `BankStats`, even though the actual operational model was slot occupancy for `GLYPH` and `SOUNDS`.
|
|
|
|
The refactor closed that gap by making the visible bank summary slot-first and moving the canonical summary ownership to `AssetManager`.
|
|
|
|
## Key Decisions
|
|
|
|
### AssetManager Owns the Visible Bank Summary
|
|
|
|
**What:**
|
|
The canonical visible bank telemetry is exposed by `AssetManager`, not by `MemoryBanks`, and uses `BankTelemetry { bank_type, used_slots, total_slots }`.
|
|
|
|
**Why:**
|
|
`AssetManager` is the domain owner that already knows loaded assets, active slot occupancy, and the bank summary that host tooling and certification need. Keeping the visible summary there prevents the abstraction from drifting into a generic but less useful lower-level surface.
|
|
|
|
**Trade-offs:**
|
|
This keeps the visible contract simpler and more explicit, but it also means low-level byte accounting and residency details cannot be treated as the primary public model anymore.
|
|
|
|
### Slot Occupancy Is the Operational Truth
|
|
|
|
**What:**
|
|
The public bank summary is slot-first. Detailed inspection remains per-slot through slot references and slot enums.
|
|
|
|
**Why:**
|
|
Banks are operated, debugged, and visualized in terms of occupied slots, not aggregate bytes. Overlay and certification become easier to understand when they read the same unit the runtime actually uses to allocate and inspect banks.
|
|
|
|
**Trade-offs:**
|
|
Byte totals may still exist internally for implementation needs, but they no longer define the public contract. Any internal byte path must stay subordinate to the slot model.
|
|
|
|
### Certification Must Share the Same Unit as Inspection
|
|
|
|
**What:**
|
|
Certification moved from `max_gfx_bytes` / `max_audio_bytes` to slot-based ceilings such as `max_glyph_slots_used` and `max_sound_slots_used`.
|
|
|
|
**Why:**
|
|
A certification rule should use the same visible semantics as overlay and diagnostics. If inspection is slot-first but certification is byte-first, engineers end up debugging two different models for the same bank state.
|
|
|
|
**Trade-offs:**
|
|
The migration removes some old byte-oriented limits, so any future need for byte budgeting must be introduced as a separate internal concern instead of piggybacking on the visible bank contract.
|
|
|
|
## Patterns and Algorithms
|
|
|
|
- Put the canonical telemetry contract at the domain owner that already knows the operational state, instead of at a lower abstraction that would need extra interpretation.
|
|
- Prefer the unit engineers actually use in debugging and operations for the public contract.
|
|
- Keep detailed inspection and summary telemetry separate:
|
|
summary telemetry answers "how full is each bank?";
|
|
slot inspection answers "what is in this slot?".
|
|
- When a public telemetry model changes units, migrate certification and debugger payloads in the same change set.
|
|
|
|
## Pitfalls
|
|
|
|
- Leaving byte-oriented helper types in the visible path keeps old semantics alive even after the new summary exists.
|
|
- Moving the generic contract too low in the stack can create an abstract API that is technically reusable but no longer aligned with the runtime's operational owner.
|
|
- Updating overlay without updating certification creates inconsistent diagnostics.
|
|
- Renaming presentation labels without aligning canonical bank names causes drift between `BankType`, telemetry payloads, and docs.
|
|
|
|
## Takeaways
|
|
|
|
- Public bank telemetry should reflect slot occupancy, not leftover byte-accounting structures.
|
|
- `AssetManager` is the right place for the canonical visible bank summary because it owns the practical bank state.
|
|
- Overlay, debugger, syscalls, and certification should all consume the same bank unit to avoid semantic drift.
|