---
id: PLN-0124
ticket: perf-async-background-work-lanes-for-assets-and-fs
title: Async Work Lane Runtime Infrastructure
status: done
created: 2026-06-28
completed:
ref_decisions: [DEC-0034]
tags: [perf, asset, fs, async, scheduler, runtime]
---

# PLN-0124 - Async Work Lane Runtime Infrastructure

## Briefing

`DEC-0034` requires one runtime-owned async work lane, separate from VM/main
execution and separate from render worker execution. This plan introduces the
lane infrastructure before migrating asset loading.

## Decisions de Origem

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

## Alvo

Create a serial async work lane primitive that can execute one active job at a
time, expose observable state, and support deterministic shutdown.

## Escopo

Included:

- Runtime-owned async work lane type.
- Single active job execution.
- Ordered pending job storage.
- Cooperative cancellation hook.
- Shutdown and join behavior.
- Basic lane telemetry.

Fora de Escopo:

- Public asset backlog syscalls.
- Asset handle model migration.
- FS public API.
- Render worker changes.

## Plano de Execucao

### Step 1 - Locate Runtime Service Boundary

**What:** Choose the crate/module boundary for the async lane.

**How:** Place generic lane infrastructure near VM runtime services, not inside
desktop host code and not inside render worker modules.

**Files:** likely `crates/console/prometeu-system/src/services/` or
`crates/console/prometeu-system/src/services/vm_runtime/`.

### Step 2 - Define Job and Lane Types

**What:** Add a lane type with pending queue, active job metadata, generation,
state, progress, and cancellation flag.

**How:** Use typed job enums or traits that do not require guest callbacks.
Start with internal asset job support but keep the lane generic enough for
memcard/FS later.

**Files:** new module under `prometeu-system` service layer.

### Step 3 - Implement Serial Worker

**What:** Implement one worker loop that takes one pending job and runs it to
completion or cooperative cancellation.

**How:** Use a fixed worker thread on host builds. Preserve a logical-lane API
so future hardware can map it to a dedicated core.

**Files:** async lane module; lifecycle wiring in VM runtime service setup.

### Step 4 - Implement Shutdown

**What:** Add explicit stop/shutdown behavior.

**How:** Wake the lane, stop accepting new jobs, report pending jobs as canceled
or shutdown-discarded, and join the worker with bounded behavior.

**Files:** async lane module and VM runtime lifecycle modules.

### Step 5 - Expose Internal Telemetry

**What:** Add counters for pending depth, active job, submitted, completed,
failed, canceled, and superseded.

**How:** Use cheap atomics or lane-owned state snapshots. Do not update
expensive percentile data inside inner decode loops.

**Files:** async lane module; telemetry structs where runtime telemetry lives.

## Criterios de Aceite

- [ ] Lane has one active job maximum.
- [ ] Lane is separate from render worker code.
- [ ] Lane can be started and stopped deterministically.
- [ ] Pending jobs are observable.
- [ ] Cooperative cancellation can be signaled.
- [ ] No guest callback path is introduced.

## Tests / Validacao

- Unit tests for enqueue, single active execution, ordering, cancellation signal,
  and shutdown.
- Concurrency tests must synchronize on real state transitions, not sleeps.
- Run targeted `cargo test` for the owning crate.

## Riscos

- Accidentally creating a generic pool instead of a serial lane.
- Coupling the lane to desktop host thread details.
- Reusing render worker handoff semantics where ordered backlog is required.