128 lines
3.9 KiB
Markdown
128 lines
3.9 KiB
Markdown
---
|
|
id: PLN-0125
|
|
ticket: perf-async-background-work-lanes-for-assets-and-fs
|
|
title: Asset Backlog and Stable Slot Handles
|
|
status: open
|
|
created: 2026-06-28
|
|
completed:
|
|
ref_decisions: [DEC-0034]
|
|
tags: [perf, asset, async, runtime]
|
|
---
|
|
|
|
# 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`, and
|
|
`request_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:
|
|
|
|
```text
|
|
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/cancel` behavior.
|