# 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.