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

# PLN-0123 - Async Work Lane Specification Propagation

## Briefing

`DEC-0034` establishes a third serial async work lane, asset backlog semantics,
stable bank-slot handles, superseding, progress, telemetry, and FS/memcard lane
boundaries. The canonical specs must be updated before code work relies on the
new contract.

## Decisions de Origem

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

## Alvo

Publish the accepted async work lane and asset backlog contract in the canonical
runtime specs.

## Escopo

Included:

- Update asset management spec.
- Update syscall ABI spec if public backlog APIs are named there.
- Update syscall policy/status language for operational asset states.
- Update events/concurrency spec with the async work lane as an implementation
  lane that does not introduce guest callbacks.
- Add a cross-reference from FS/app-home agenda or notes to the async IO lane.

Fora de Escopo:

- Implementing runtime code.
- Finalizing public FS API semantics.
- Changing render worker contracts.

## Plano de Execucao

### Step 1 - Update Asset Management

**What:** Add the third async lane, backlog, handle, superseding, progress, and
telemetry contract.

**How:** Extend `docs/specs/runtime/15-asset-management.md` around the existing
`asset.load/status/commit/cancel` section. Preserve the existing
`asset.load(asset_id, slot)` identity contract.

**Files:** `docs/specs/runtime/15-asset-management.md`.

### Step 2 - Update Host ABI

**What:** Add the backlog API direction if the ABI spec is the canonical place
for syscall shapes.

**How:** Extend the asset surface section with the planned backlog operations,
marking exact numeric ids as implementation-plan work if ids are not assigned
yet.

**Files:** `docs/specs/runtime/16-host-abi-and-syscalls.md`.

### Step 3 - Update Syscall Policies

**What:** Clarify that `superseded`, `canceled`, `backend_unavailable`, and
decode failures are operational statuses, not faults.

**How:** Add asset-domain examples under status-first policy.

**Files:** `docs/specs/runtime/16a-syscall-policies.md`.

### Step 4 - Update Events and Concurrency

**What:** Document that the async work lane is an implementation lane.

**How:** Add a section next to render worker concurrency stating that asset/IO
lane work does not introduce guest callbacks or hidden guest execution.

**Files:** `docs/specs/runtime/09-events-and-concurrency.md`.

### Step 5 - Cross-Reference FS Work

**What:** Record that FS may consume the async IO lane, while public FS API
semantics remain owned by the app-home filesystem discussion.

**How:** Add a note in `AGD-0006` or its future decision input, without deciding
FS request/poll shape in this plan.

**Files:** `discussion/workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md`.

## Criterios de Aceite

- [ ] Specs state that the async work lane is serial and separate from render.
- [ ] Asset spec states backlog keying by `bank_type/slot`.
- [ ] Asset spec states stable slot handles with `slot_state` and `request_state`.
- [ ] Asset spec states superseding behavior.
- [ ] Asset spec states main-lane commit/install.
- [ ] FS is cross-referenced as a permitted lane consumer without public API decisions.

## Tests / Validacao

- Run `discussion validate`.
- Review spec links for broken relative paths.
- No cargo tests are required for this documentation-only plan.

## Riscos

- Public ABI names may be refined later; the spec must avoid assigning ids too
  early if implementation work has not reserved them.
- FS scope can leak into this work; keep FS public API decisions in `AGD-0006`.