3.9 KiB
| id | ticket | title | status | created | completed | ref_decisions | tags | |||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| PLN-0125 | perf-async-background-work-lanes-for-assets-and-fs | Asset Backlog and Stable Slot Handles | done | 2026-06-28 |
|
|
PLN-0125 - Asset Backlog and Stable Slot Handles
Briefing
DEC-0034 changes asset loading from request-owned thread spawning to a serial
backlog keyed by bank_type/slot. Handles become stable bank-slot observers
with separate resident slot state and request state.
Decisions de Origem
DEC-0034- Async Work Lane and Asset Backlog Contract.
Alvo
Refactor AssetManager so asset requests are tracked by target bank slot,
deduplicated/superseded by target, and observable through stable handles.
Escopo
Included:
- Stable handle structure with
bank_type,slot,slot_state, andrequest_state. - Backlog keyed by
bank_type/slot. - Already-resident fast path.
- Superseding for queued and active requests.
- Main-lane commit/install boundary.
Fora de Escopo:
- Public backlog syscall wiring.
- Percentile telemetry.
- FS public API.
Plano de Execucao
Step 1 - Model Slot Handles
What: Replace transient load-operation assumptions with stable bank-slot handle state.
How: Introduce structures equivalent to:
handle: bank_type, slot
slot_state: loaded_asset_id, resident_state, slot_generation
request_state: requested_asset_id, request_generation, state, position, progress
Files: crates/console/prometeu-drivers/src/asset.rs and HAL asset types if
public type definitions belong there.
Step 2 - Key Backlog by Target
What: Ensure at most one current request per bank_type/slot.
How: Add a target index from (bank_type, slot) to current request
generation/handle state. Enqueue only when the target does not already have the
same resident asset and no newer request supersedes it.
Files: crates/console/prometeu-drivers/src/asset.rs.
Step 3 - Implement Already-Resident Fast Path
What: Return a ready handle immediately when the requested asset already resides in the target slot.
How: Compare requested asset_id with the target slot_state.loaded_asset_id
and resident validity before creating a queued job.
Files: crates/console/prometeu-drivers/src/asset.rs.
Step 4 - Implement Superseding
What: New request for the same target supersedes previous queued or active request.
How: Remove queued older request immediately. For active work, update target generation so the old result is discarded if it cannot stop cooperatively.
Files: crates/console/prometeu-drivers/src/asset.rs; async lane module
from PLN-0124.
Step 5 - Preserve Main-Lane Commit
What: Keep install/commit into resident banks on the main runtime lane.
How: Async lane produces staged materialized result. asset.commit(handle)
installs only when the request generation is current and ready.
Files: crates/console/prometeu-drivers/src/asset.rs; VM runtime dispatch if
commit behavior changes.
Criterios de Aceite
- No asset load spawns an OS thread per request.
- At most one request exists per
bank_type/slot. - Same-target newer request supersedes older queued request.
- Same-target newer request prevents active stale result from installing.
- Already-resident target returns ready handle without backlog entry.
- Handles remain queryable for empty, queued, active, ready, committed, canceled, superseded, and error states.
Tests / Validacao
- Unit tests for handle state transitions.
- Unit tests for target-keyed superseding.
- Unit tests for already-resident fast path.
- Integration test for stale active result discard.
- Existing asset load/commit tests must continue passing.
Riscos
- Confusing handle identity with request generation.
- Installing a stale async result after superseding.
- Losing compatibility with existing
asset.status/commit/cancelbehavior.