178 lines
4.2 KiB
Markdown
178 lines
4.2 KiB
Markdown
# Asset Management
|
|
|
|
Domain: asset runtime surface
|
|
Function: normative
|
|
|
|
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.
|
|
|
|
## 11 Syscall Surface and Status Policy
|
|
|
|
`asset` follows status-first policy.
|
|
|
|
Fault boundary:
|
|
|
|
- `Trap`: structural ABI misuse (type/arity/capability/shape mismatch);
|
|
- `status`: operational failure;
|
|
- `Panic`: internal invariant break only.
|
|
|
|
### 11.1 MVP syscall shape
|
|
|
|
- `asset.load(name, kind, slot) -> (status:int, handle:int)`
|
|
- `asset.status(handle) -> status:int`
|
|
- `asset.commit(handle) -> status:int`
|
|
- `asset.cancel(handle) -> status:int`
|
|
|
|
Rules:
|
|
|
|
- `handle` is valid only when `load` status is `OK`;
|
|
- failed `load` returns `handle = 0`;
|
|
- `commit` and `cancel` must not be silent no-op for unknown/invalid handle state.
|
|
|
|
### 11.2 Minimum status tables
|
|
|
|
`asset.load` request statuses:
|
|
|
|
- `0` = `OK`
|
|
- `3` = `ASSET_NOT_FOUND`
|
|
- `4` = `SLOT_KIND_MISMATCH`
|
|
- `5` = `SLOT_INDEX_INVALID`
|
|
- `6` = `BACKEND_ERROR`
|
|
|
|
`asset.status` lifecycle statuses:
|
|
|
|
- `0` = `PENDING`
|
|
- `1` = `LOADING`
|
|
- `2` = `READY`
|
|
- `3` = `COMMITTED`
|
|
- `4` = `CANCELED`
|
|
- `5` = `ERROR`
|
|
- `6` = `UNKNOWN_HANDLE`
|
|
|
|
`asset.commit` and `asset.cancel` operation statuses:
|
|
|
|
- `0` = `OK`
|
|
- `1` = `UNKNOWN_HANDLE`
|
|
- `2` = `INVALID_STATE`
|