bQUARKz
0adec90f23
Some checks failed
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
127 lines
3.8 KiB
Markdown
127 lines
3.8 KiB
Markdown
---
|
|
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.
|