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 Artifact

The runtime currently consumes one primary cartridge asset artifact:

• assets.pa: autocontained asset artifact.

assets.pa carries, inside the same binary:

• fixed binary prelude;
• JSON header;
• payload bytes.

The JSON header carries:

• asset_table: metadata entries describing asset content;
• preload: optional initial residency requests consumed during cartridge initialization.

This chapter describes the runtime-facing asset contract. It does not define the Studio packer workflow or the shipper pipeline that publishes the cartridge.

3.1 assets.pa v1 envelope

assets.pa v1 is structured as:

[fixed binary prelude]
[json header]
[binary payload region]

The fixed binary prelude contains, at minimum:

• magic
• schema_version
• header_len
• payload_offset

It may additionally include:

• flags
• reserved
• header_checksum

3.2 Header and payload contract

The runtime loads:

• asset_table from the JSON header and keeps it live during cartridge execution;
• preload from the JSON header and consumes it only during boot.

Payload bytes are addressed from the payload region using offsets relative to payload_offset, not relative to the start of the whole file.

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.

asset_id is the stable runtime-facing asset identity and uses 32-bit signed integer semantics compatible with Java int.

offset is relative to the start of the payload region inside assets.pa.

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. resolve the asset entry from live asset_table;
3. open the payload slice in assets.pa;
4. perform read/decode/materialization work;
5. mark the load READY;
6. explicitly commit;
7. activate the resident asset in the slot.

The canonical payload paths are:

• ROM -> open_slice -> CODEX/decode -> Bank
• ROM -> open_slice -> temporary in-memory blob -> CODEX/decode -> Bank

open_slice is the runtime-facing concept for opening a limited view over a payload slice. The runtime must not require the whole assets.pa payload to remain resident in RAM as its baseline operating mode.

OP_MODE selects between direct slice consumption and temporary materialization in memory.

For v1:

• OP_MODE is derived from codec/CODEX;
• explicit per-asset hinting is not part of the baseline contract.

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.
• the runtime must not keep the full assets.pa payload resident in RAM as a baseline requirement.

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

preload is stored in the JSON header of assets.pa.

The normative preload shape is:

PreloadEntry {
  asset_id
  slot
}

These preload entries are consumed during cartridge initialization so the asset manager can establish initial residency before normal execution flow.

Validation rules:

• preload is resolved by asset_id, not by asset_name;
• every preload.asset_id must exist in the same asset_table;
• no two preload entries may resolve to the same (bank_type, slot) pair;
• legacy preload keyed by asset_name is invalid for the current contract.

Lifecycle rule:

• preload is boot-time input only;
• it does not need to remain live after initialization completes.

Bootstrap rule:

• invalid preload is a structural cartridge error and must fail cartridge bootstrap before normal execution begins.

10 Relationship to Other Specs

• 13-cartridge.md defines the cartridge package and the requirement that assets.pa carries its own asset header.
• 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.
• slot validation, kind mismatch, and residency/lifecycle rejection remain in asset status space and are not delegated to bank.

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