prometeu-runtime/discussion/workflow/plans/PLN-0126-asset-backlog-public-api-and-status-surface.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0126	perf-async-background-work-lanes-for-assets-and-fs	Asset Backlog Public API and Status Surface	open	2026-06-28		DEC-0034	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:

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.