prometeu-runtime/docs/runtime/specs/15-asset-management.md

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:

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:

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 defines cartridge fields that carry asset_table, preload, and assets.pa.
• 16-host-abi-and-syscalls.md defines the syscall boundary used to manipulate assets.
• 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