---
id: PLN-0128
ticket: perf-async-background-work-lanes-for-assets-and-fs
title: Async Asset Pipeline Contract Tests and Telemetry
status: done
created: 2026-06-28
completed:
ref_decisions: [DEC-0034]
tags: [perf, asset, async, telemetry, tests, runtime]
---

# PLN-0128 - Async Asset Pipeline Contract Tests and Telemetry

## Briefing

`DEC-0034` requires observable progress, backlog state, superseding, and cheap
telemetry. This plan adds the validation and telemetry evidence needed to prove
the new async asset pipeline is correct.

## Decisions de Origem

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

## Alvo

Provide contract tests and telemetry for the async asset lane so future
implementations can be changed without regressing lane semantics.

## Escopo

Included:

- Contract tests for lane and asset backlog behavior.
- Progress reporting tests.
- Superseding and stale result discard tests.
- Telemetry counters and percentile updates.
- No-sleep deterministic test helpers where needed.

Fora de Escopo:

- Implementing public API wiring if `PLN-0126` has not run.
- Full benchmarking infrastructure.
- Host UI display of telemetry.

## Plano de Execucao

### Step 1 - Build Deterministic Test Hooks

**What:** Add test hooks for blocking a lane job at read/decode/stage.

**How:** Use channels/barriers or explicit fake job steps. Do not rely on
`thread::sleep` for correctness.

**Files:** async lane tests; asset test support modules.

### Step 2 - Test Backlog Ordering

**What:** Prove queued jobs run serially and in backlog order.

**How:** Submit multiple target slots and assert active job, pending positions,
promote, demote, and move behavior.

**Files:** asset manager tests and lane tests.

### Step 3 - Test Superseding

**What:** Prove newer request for the same `bank_type/slot` supersedes older
requests.

**How:** Cover queued superseding and active superseding. For active work, prove
stale completion cannot install.

**Files:** asset manager tests.

### Step 4 - Test Stable Handle Observability

**What:** Prove handles are queryable for empty, queued, active, ready,
committed, canceled, superseded, and error states.

**How:** Use `target_status` and handle status APIs to inspect both `slot_state`
and `request_state`.

**Files:** asset manager tests; VM dispatch tests if public API is available.

### Step 5 - Test Progress

**What:** Prove progress uses `0..10000` and phase boundaries.

**How:** Fake read/decode/stage phases with known completion points. Validate
non-linear phases do not report false internal progress.

**Files:** asset manager tests; telemetry tests.

### Step 6 - Add Telemetry

**What:** Add counters and percentile aggregation.

**How:** Update submitted/completed/failed/canceled/superseded counters when job
state closes. Update percentiles by `bank_type` and lightweight `asset_id`
window only at job completion.

**Files:** asset manager telemetry, async lane telemetry, existing runtime
telemetry types if shared.

## Criterios de Aceite

- [ ] Tests prove one active job at a time.
- [ ] Tests prove backlog order and reordering.
- [ ] Tests prove queued and active superseding.
- [ ] Tests prove stale active results are discarded.
- [ ] Tests prove handles remain queryable across all required states.
- [ ] Tests prove progress phase behavior.
- [ ] Telemetry is updated at job closure, not inside inner decode loops.

## Tests / Validacao

- Run targeted cargo tests for asset manager, async lane, and VM runtime
  dispatch.
- Run existing asset-bank tests to prove current behavior remains compatible.
- Run `discussion validate` after plan state changes.

## Riscos

- Tests that depend on sleeps will be flaky.
- Telemetry may become too expensive if updated inside decode loops.
- Public API tests must wait for `PLN-0126` if syscall wiring is not present.