prometeu-runtime/discussion/workflow/plans/PLN-0128-async-asset-pipeline-contract-tests-and-telemetry.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0128	perf-async-background-work-lanes-for-assets-and-fs	Async Asset Pipeline Contract Tests and Telemetry	open	2026-06-28		DEC-0034	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.