asset manager load by asset id and slot index

This commit is contained in:
2026-03-27 15:05:37 +00:00
parent e6978397ab
commit 201226b892
13 changed files with 154 additions and 186 deletions
+9 -6
View File
@@ -163,15 +163,17 @@ The current runtime exposes bank types:
- `TILES`
- `SOUNDS`
Assets are loaded into explicit slots identified by bank context plus index.
Assets are loaded into explicit slots identified by slot index at the public ABI boundary.
Conceptual slot reference:
The runtime resolves bank context from `asset_table` using `asset_id`.
Internally, the runtime may still use a bank-qualified slot reference such as:
```text
SlotRef { bank_type, index }
```
This prevents ambiguity between graphics and audio residency.
That internal representation is derived from the resolved `AssetEntry`, not supplied by the caller.
## 6 Load Lifecycle
@@ -285,7 +287,7 @@ Fault boundary:
### 11.1 MVP syscall shape
- `asset.load(name, kind, slot) -> (status:int, handle:int)`
- `asset.load(asset_id, slot) -> (status:int, handle:int)`
- `asset.status(handle) -> status:int`
- `asset.commit(handle) -> status:int`
- `asset.cancel(handle) -> status:int`
@@ -295,7 +297,9 @@ 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`.
- `asset.load` resolves the target bank type from `asset_table` using `asset_id`;
- public callers must not supply `asset_name` or `bank_type` to `asset.load`;
- slot validation and residency/lifecycle rejection remain in `asset` status space and are not delegated to `bank`.
### 11.2 Minimum status tables
@@ -303,7 +307,6 @@ Rules:
- `0` = `OK`
- `3` = `ASSET_NOT_FOUND`
- `4` = `SLOT_KIND_MISMATCH`
- `5` = `SLOT_INDEX_INVALID`
- `6` = `BACKEND_ERROR`
@@ -181,6 +181,23 @@ Canonical operations in v1 are:
Semantics and domain status catalog are defined by [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md).
### Asset surface (`asset`, v1)
The asset runtime surface also follows the status-first ABI shape.
Canonical operations in v1 are:
- `asset.load(asset_id, slot) -> (status, handle)`
- `asset.status(handle) -> status`
- `asset.commit(handle) -> status`
- `asset.cancel(handle) -> status`
For `asset.load`:
- `asset_id` is a signed 32-bit runtime identity;
- `slot` is the target slot index;
- bank kind is resolved from `asset_table` by `asset_id`, not supplied by the caller.
## 7 Syscalls as Callable Entities (Not First-Class)
Syscalls behave like call sites, not like first-class guest values.
+1
View File
@@ -149,6 +149,7 @@ The verifier statically checks bytecode for structural safety and stack‑shape
- `SyscallMeta` defines expected arity and return slot counts. The loader resolves `HOSTCALL` against this metadata and rejects raw `SYSCALL` in PBX pre-load artifacts; the verifier checks final IDs/arity/return‑slot counts against the same metadata.
- Arguments and returns
- Arguments are taken from the operand stack in the order defined by the ABI. Returns use multi‑slot results via a host‑side return buffer (`HostReturn`) which the VM copies back onto the stack, or zero slots for “void”. A mismatch in result counts is a fault/panic per current hardening logic.
- Example: the canonical asset runtime load surface is `asset.load(asset_id, slot) -> (status, handle)`. The caller does not supply `asset_name` or `asset_type`; bank kind is derived from `asset_table` using `asset_id`.
- Capabilities
- Cartridge capability flags are applied before load-time host resolution. Missing required capability aborts load; invoking a syscall without the required capability also traps defensively at runtime.
+8
View File
@@ -78,6 +78,14 @@ Authority rule:
- `INTRINSIC u32` — final numeric VM-owned intrinsic call.
- `FRAME_SYNC` — yield until the next frame boundary (e.g., vblank); explicit safepoint.
Host service arity is not encoded in the opcode itself. It is defined by resolved syscall metadata.
Example:
- `asset.load` currently resolves with `arg_slots = 2` and `ret_slots = 2`.
- The canonical stack contract is `asset_id, slot -> status, handle`.
- Callers do not provide an explicit asset kind; the runtime derives it from `asset_table`.
#### Canonical Intrinsic Registry Artifact
- Final intrinsic IDs and intrinsic stack metadata are published in [`INTRINSICS.csv`](INTRINSICS.csv).