125 lines
3.5 KiB
Markdown
125 lines
3.5 KiB
Markdown
---
|
|
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.
|