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