---
id: DEC-0034
ticket: perf-async-background-work-lanes-for-assets-and-fs
title: Async Work Lane and Asset Backlog Contract
status: accepted
created: 2026-06-28
accepted: 2026-06-28
ref_agenda: AGD-0008
plans: [PLN-0123, PLN-0124, PLN-0125, PLN-0126, PLN-0127, PLN-0128]
tags: [perf, asset, fs, async, scheduler, runtime]
---

# DEC-0034 - Async Work Lane and Asset Backlog Contract

## Status

Accepted.

## Contexto

`asset.load()` currently creates an OS thread per non-resident asset request.
That behavior does not match the target runtime model: the machine should have
explicit execution lanes, bounded ownership, observable backpressure, and no
uncontrolled thread creation from guest-visible operations.

Render worker concurrency is already handled by separate render decisions. This
decision covers the third runtime lane for asynchronous IO/decode/persistence
work:

```text
Lane 1: VM, firmware, SystemOS, logical frame
Lane 2: render worker / asynchronous rasterization
Lane 3: async work lane for asset IO/decode and game persistence work
```

The concrete first consumer is asset loading. Game persistence through memcard
may also consume this lane. FS is allowed to consume this lane, but public FS API
shape belongs to the app-home filesystem agenda.

## Decisao

Prometeu MUST introduce a third async work lane as the runtime-owned execution
place for asset IO/decode work and compatible persistence IO work.

The async work lane MUST be serial: it has exactly one active job at a time.
The runtime MUST NOT create one OS thread per `asset.load` request in the normal
path.

Asset loading MUST use a backlog keyed by target `bank_type/slot`. A target can
have at most one current request. A newer request for the same `bank_type/slot`
MUST supersede the previous request for that target.

Asset handles MUST represent stable bank slots, not transient worker threads.
A handle MUST remain queryable even when the slot has no valid loaded asset and
even when there is no active request for that slot. The handle state MUST
separate resident slot state from request/backlog state.

Asset IO/read and decode/materialization MUST run on the async work lane.
Asset install/commit into resident banks MUST happen on the main runtime lane at
predictable ownership points.

Memcard work MAY consume the same async work lane and has higher priority than
ordinary asset loads when contention exists. FS MAY consume the same lane for
IO-style work, but this decision does not define the public FS API.

## Rationale

A serial lane maps cleanly to the intended third-core mental model and avoids a
desktop-biased generic thread pool. It gives the runtime one place to observe
IO/decode backlog, progress, priority, cancellation, and telemetry.

Keying requests by `bank_type/slot` makes the backlog naturally bounded by the
sum of bank slots. There is no need for a guest-visible `queue_full` state:
there cannot be unbounded distinct pending targets if each target has at most
one current request.

Keeping commit/install on the main lane preserves deterministic publication
semantics and avoids letting the async lane mutate resident graphics/audio/scene
state while the VM, render handoff, or frame boundary is observing it.

Separating `slot_state` and `request_state` inside the handle avoids ambiguity:
callers can inspect the slot at any time, while mutating operations still remain
protected by request generation.

## Invariantes / Contrato

### Async Work Lane

- The async work lane MUST be runtime-owned.
- The async work lane MUST be separate from the render worker.
- The async work lane MUST execute at most one active job at a time.
- The runtime MUST NOT use `thread::spawn` per asset request in the normal
  asset loading path.
- The host may implement the lane as a fixed worker thread. Hardware targets may
  map it to a dedicated core when available.
- If a physical third core is unavailable, the implementation MUST preserve the
  same logical lane contract.

### Asset Backlog

- Asset requests MUST target a concrete `bank_type/slot`.
- The backlog is ordered and serial.
- Each `bank_type/slot` MUST have at most one current request.
- A newer request for the same `bank_type/slot` MUST supersede any earlier
  pending request for that target.
- If the target already contains the requested `asset_id` as a valid resident
  asset, `asset.load` MUST return a handle in ready state without adding a job
  to the backlog.
- The effective backlog size is bounded by the sum of targetable bank slots,
  even though the contract does not expose a fixed queue limit.
- Implementations MUST collect stale metadata for canceled or superseded
  requests so the handle/request history does not grow without bound.

### Handles

An asset handle MUST represent a stable bank slot target. The handle state MUST
include at least:

```text
handle:
  bank_type
  slot

slot_state:
  loaded_asset_id
  resident_state
  slot_generation

request_state:
  requested_asset_id
  request_generation
  state
  backlog_position
  progress
```

The handle MUST be queryable when:

- the slot is empty;
- the slot contains a valid resident asset;
- a request is queued;
- a request is active;
- a request is ready for commit;
- a request has been canceled;
- a request has been superseded;
- a request ended in error.

Mutating operations such as commit, cancel, promote, demote, or move MUST act on
the current request generation. They MUST NOT accidentally mutate a newer
request through an older handle view.

### Superseding

`superseded` means a request was replaced by a newer request for the same
`bank_type/slot`.

- Superseding is an operational state, not a fault.
- If the old request is queued, it MUST be removed from the backlog.
- If the old request is active, the lane SHOULD cancel cooperatively when the
  current phase supports cheap cancellation.
- If active work cannot be interrupted cheaply, it MAY finish, but its result
  MUST be discarded when its generation no longer matches the target's current
  request generation.

### Asset Backlog API Direction

The existing asset operations remain the base surface:

```text
asset.load(asset_id, slot) -> (status, handle)
asset.status(handle) -> status
asset.commit(handle) -> status
asset.cancel(handle) -> status
```

The asset backlog surface SHOULD add a small status-first API:

```text
asset.backlog_info()
  -> (status, pending_count, active_handle, active_asset_id,
      active_bank_type, active_slot, active_progress)

asset.backlog_position(handle)
  -> (status, state, position, progress)

asset.backlog_move(handle, new_position)
  -> status

asset.backlog_promote(handle)
  -> status

asset.backlog_demote(handle)
  -> status

asset.target_status(bank_type, slot)
  -> (status, asset_id, handle, state, position, progress)
```

`asset.backlog_promote(handle)` is an official shortcut for moving a queued
request to position `1`, the first pending position after the active job.

`asset.backlog_demote(handle)` is an official shortcut for moving a queued
request to the end of the pending backlog.

The final ABI names and exact return shapes may be refined during planning, but
the implementation MUST preserve the capabilities above.

### Progress

Progress MUST be represented without floating point. The recommended scale is
`0..10000`.

The initial phase model is:

```text
queued -> 0
read   -> 0..4000
decode -> 4000..9000
stage  -> 9000..10000
ready  -> 10000
```

If a phase cannot report internal progress, it MUST keep the previous progress
mark and advance at phase completion. Implementations MUST NOT invent false
precision for non-linear decode phases.

### Telemetry

Telemetry MUST be cheap and must not add hot-path per-item decode cost.

Minimum telemetry:

- current backlog depth;
- target/request position;
- active job progress;
- jobs submitted;
- jobs completed;
- jobs failed;
- jobs canceled;
- jobs superseded;
- job duration;
- percentiles by `bank_type`;
- lightweight percentiles or small-window samples by `asset_id`.

Percentiles MUST be updated when a job closes, not inside the inner decode loop.

### Priority

When async lane consumers contend, the initial priority order is:

1. memcard commit/write;
2. FS write/config work;
3. asset visual/audio/scene load;
4. non-critical list/read work.

This priority order is a lane arbitration rule. It does not define public FS
syscall semantics.

### FS Boundary

FS MAY consume the async work lane for IO-style work.

This decision MUST NOT define the public FS API, app-home FS semantics, or
whether FS is exposed as request/poll or sync-appearing operations. Those
questions belong to `AGD-0006`.

`AGD-0006` MUST be updated or interpreted with the existence of this async IO
lane in mind.

## Impactos

### Spec

- `docs/specs/runtime/15-asset-management.md` must absorb the async lane,
  backlog, handle, superseding, progress, and telemetry contract.
- `docs/specs/runtime/16-host-abi-and-syscalls.md` must absorb any final public
  asset backlog syscall names and return shapes.
- `docs/specs/runtime/16a-syscall-policies.md` may need status catalog updates
  for superseded/canceled/backend unavailable states if not already covered by
  asset domain status.
- `docs/specs/runtime/09-events-and-concurrency.md` should mention the async
  work lane as an implementation-side lane that does not introduce guest
  callbacks.
- `AGD-0006` / future FS spec work must account for FS as a possible consumer of
  the async IO lane.

### Runtime

- Asset loading must stop spawning a thread per request.
- AssetManager needs a serial backlog keyed by `bank_type/slot`.
- Asset handles need stable slot identity plus separated `slot_state` and
  `request_state`.
- Commit/install remains a main-lane operation.
- Superseding and generation checks become required correctness mechanisms.

### Host

- Desktop host may implement the async work lane with one fixed worker thread.
- Host presentation/render worker remains separate and unaffected.

### Firmware

- No direct firmware behavior is required for asset backlog mechanics.
- Firmware flows that rely on preload or memcard may later use lane telemetry or
  priority policy if needed.

### Tooling

- Test tools may need support for inspecting backlog state and forcing request
  ordering.
- Asset fixtures should cover queued, active, ready, canceled, superseded, and
  already-resident paths.

## Referencias

- `AGD-0008` - Async Background Work Lanes for Assets and FS.
- `docs/specs/runtime/15-asset-management.md`
- `docs/specs/runtime/16-host-abi-and-syscalls.md`
- `docs/specs/runtime/16a-syscall-policies.md`
- `docs/specs/runtime/09-events-and-concurrency.md`
- `docs/specs/runtime/08-save-memory-and-memcard.md`
- `AGD-0006` - App Home Filesystem Surface and Semantics.

## Propagacao Necessaria

1. Update asset management specs with the lane/backlog/handle contract.
2. Update syscall specs if backlog APIs become public ABI.
3. Update FS agenda/spec work to acknowledge the async IO lane without deciding
   FS public API in this decision.
4. Plan implementation of a serial async work lane and asset backlog.
5. Plan tests for superseding, stable slot handles, immediate-ready resident
   assets, progress, telemetry, and main-lane commit.

## Revision Log

- 2026-06-28: Initial draft from `AGD-0008`.