---
id: PLN-0126
ticket: perf-async-background-work-lanes-for-assets-and-fs
title: Asset Backlog Public API and Status Surface
status: open
created: 2026-06-28
completed:
ref_decisions: [DEC-0034]
tags: [perf, asset, async, syscall, runtime]
---

# PLN-0126 - Asset Backlog Public API and Status Surface

## Briefing

`DEC-0034` keeps `asset.load/status/commit/cancel` and adds a small status-first
backlog inspection and ordering surface. This plan wires that surface through
HAL syscall metadata and runtime dispatch.

## Decisions de Origem

- `DEC-0034` - Async Work Lane and Asset Backlog Contract.

## Alvo

Expose asset backlog inspection and reordering while preserving status-first
semantics and existing asset load identity.

## Escopo

Included:

- Syscall registry additions for backlog APIs.
- Runtime dispatch handlers.
- Status enum additions or normalization.
- ABI/spec alignment with `PLN-0123`.

Fora de Escopo:

- Async lane internals.
- Asset decode refactor.
- FS API.

## Plano de Execucao

### Step 1 - Finalize Syscall Shapes

**What:** Choose final names, arity, and return slots for backlog operations.

**How:** Start from `DEC-0034`:

```text
asset.backlog_info()
asset.backlog_position(handle)
asset.backlog_move(handle, new_position)
asset.backlog_promote(handle)
asset.backlog_demote(handle)
asset.target_status(bank_type, slot)
```

**Files:** `crates/console/prometeu-hal/src/syscalls/domains/asset.rs`,
`docs/specs/runtime/16-host-abi-and-syscalls.md`.

### Step 2 - Add Status Values

**What:** Represent `empty`, `invalid`, `queued`, `active`, `ready`,
`committed`, `canceled`, `superseded`, `error`, and `backend_unavailable`.

**How:** Extend or map existing `LoadStatus` and `AssetOpStatus` without
turning operational states into traps.

**Files:** HAL asset status types and `crates/console/prometeu-drivers/src/asset.rs`.

### Step 3 - Add Dispatch

**What:** Wire new syscalls through VM runtime dispatch.

**How:** Add match arms near existing `AssetLoad`, `AssetStatus`,
`AssetCommit`, and `AssetCancel` arms. Return status-first values.

**Files:** `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`.

### Step 4 - Implement API Methods

**What:** Add AssetManager methods backing each public operation.

**How:** Methods must read stable handle/target state and reorder only queued
requests. `promote` and `demote` are shortcuts over move semantics.

**Files:** `crates/console/prometeu-drivers/src/asset.rs`.

### Step 5 - Validate ABI Metadata

**What:** Ensure registry ids, args, returns, capability, cost, and
non-deterministic flags are correct.

**How:** Update syscall metadata tests and any declared PBS/runtime syscall
tables.

**Files:** `crates/console/prometeu-hal/src/syscalls/tests.rs` and related
registry files.

## Criterios de Aceite

- [ ] Public backlog operations are registered with stable metadata.
- [ ] All backlog operations are status-first.
- [ ] `promote` is equivalent to moving to first pending position.
- [ ] `demote` moves to the end of pending backlog.
- [ ] Reordering a non-queued request returns operational status.
- [ ] Structural ABI misuse remains Trap.

## Tests / Validacao

- HAL syscall metadata tests.
- VM runtime dispatch tests for each new syscall.
- AssetManager unit tests for move/promote/demote.
- Tests for `target_status` on empty, queued, active, ready, and superseded
  targets.

## Riscos

- Adding too many public ABI details before spec propagation is accepted.
- Returning payload values that are ambiguous when status is not success.
- Treating known but non-mutable states as traps instead of statuses.