126 lines
3.0 KiB
Markdown
126 lines
3.0 KiB
Markdown
# Asset Management
|
|
|
|
This chapter defines the runtime-facing asset model of PROMETEU.
|
|
|
|
## 1 Scope
|
|
|
|
PROMETEU asset management is bank-centric.
|
|
|
|
Assets are:
|
|
|
|
- cold bytes stored in the cartridge;
|
|
- described by cartridge metadata;
|
|
- materialized into host-managed banks;
|
|
- separate from VM heap ownership.
|
|
|
|
This chapter describes the runtime contract currently visible in the codebase. It is not a full tooling pipeline specification.
|
|
|
|
## 2 Core Principles
|
|
|
|
1. asset residency is explicit;
|
|
2. asset memory belongs to the machine, not to the VM heap;
|
|
3. banks and slots are hardware/runtime concepts;
|
|
4. loading and activation are explicit operations;
|
|
5. asset memory does not participate in GC.
|
|
|
|
## 3 Cartridge Asset Surfaces
|
|
|
|
The runtime currently consumes two cartridge asset surfaces:
|
|
|
|
- `asset_table`: metadata entries describing asset content;
|
|
- `assets.pa`: packed asset bytes.
|
|
|
|
An optional `preload` list may request initial slot residency during cartridge initialization.
|
|
|
|
## 4 Asset Table
|
|
|
|
Current runtime-facing asset metadata includes:
|
|
|
|
```text
|
|
AssetEntry {
|
|
asset_id
|
|
asset_name
|
|
bank_type
|
|
offset
|
|
size
|
|
decoded_size
|
|
codec
|
|
metadata
|
|
}
|
|
```
|
|
|
|
This table describes content identity and storage layout, not live residency.
|
|
|
|
## 5 Banks and Slots
|
|
|
|
The current runtime exposes bank types:
|
|
|
|
- `TILES`
|
|
- `SOUNDS`
|
|
|
|
Assets are loaded into explicit slots identified by bank context plus index.
|
|
|
|
Conceptual slot reference:
|
|
|
|
```text
|
|
SlotRef { bank_type, index }
|
|
```
|
|
|
|
This prevents ambiguity between graphics and audio residency.
|
|
|
|
## 6 Load Lifecycle
|
|
|
|
The runtime asset manager exposes a staged lifecycle:
|
|
|
|
- `PENDING`
|
|
- `LOADING`
|
|
- `READY`
|
|
- `COMMITTED`
|
|
- `CANCELED`
|
|
- `ERROR`
|
|
|
|
High-level flow:
|
|
|
|
1. request load of an asset into a slot;
|
|
2. perform read/decode/materialization work;
|
|
3. mark the load `READY`;
|
|
4. explicitly `commit`;
|
|
5. activate the resident asset in the slot.
|
|
|
|
The runtime does not treat asset installation as implicit side effect.
|
|
|
|
## 7 Residency and Ownership
|
|
|
|
Asset banks are host/runtime-owned memory.
|
|
|
|
Therefore:
|
|
|
|
- VM heap does not own asset residency;
|
|
- GC does not scan asset bank memory;
|
|
- shutting down a cartridge can release bank residency independently of VM heap behavior.
|
|
|
|
## 8 Bank Telemetry
|
|
|
|
The runtime surfaces bank and slot statistics such as:
|
|
|
|
- total bytes;
|
|
- used bytes;
|
|
- free bytes;
|
|
- inflight bytes;
|
|
- slot occupancy;
|
|
- resident asset identity per slot.
|
|
|
|
These metrics support debugging, telemetry, and certification-oriented inspection.
|
|
|
|
## 9 Preload
|
|
|
|
The cartridge may declare preload requests.
|
|
|
|
These preload entries are consumed during cartridge initialization so the asset manager can establish initial residency before normal execution flow.
|
|
|
|
## 10 Relationship to Other Specs
|
|
|
|
- [`13-cartridge.md`](13-cartridge.md) defines cartridge fields that carry `asset_table`, `preload`, and `assets.pa`.
|
|
- [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) defines the syscall boundary used to manipulate assets.
|
|
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines the distinction between VM heap memory and host-owned memory.
|