prometeu-runtime/discussion/workflow/plans/PLN-0124-async-work-lane-runtime-infrastructure.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0124	perf-async-background-work-lanes-for-assets-and-fs	Async Work Lane Runtime Infrastructure	open	2026-06-28		DEC-0034	perf asset fs async scheduler runtime

PLN-0124 - Async Work Lane Runtime Infrastructure

Briefing

DEC-0034 requires one runtime-owned async work lane, separate from VM/main execution and separate from render worker execution. This plan introduces the lane infrastructure before migrating asset loading.

Decisions de Origem

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

Alvo

Create a serial async work lane primitive that can execute one active job at a time, expose observable state, and support deterministic shutdown.

Escopo

Included:

• Runtime-owned async work lane type.
• Single active job execution.
• Ordered pending job storage.
• Cooperative cancellation hook.
• Shutdown and join behavior.
• Basic lane telemetry.

Fora de Escopo:

• Public asset backlog syscalls.
• Asset handle model migration.
• FS public API.
• Render worker changes.

Plano de Execucao

Step 1 - Locate Runtime Service Boundary

What: Choose the crate/module boundary for the async lane.

How: Place generic lane infrastructure near VM runtime services, not inside desktop host code and not inside render worker modules.

Files: likely crates/console/prometeu-system/src/services/ or crates/console/prometeu-system/src/services/vm_runtime/.

Step 2 - Define Job and Lane Types

What: Add a lane type with pending queue, active job metadata, generation, state, progress, and cancellation flag.

How: Use typed job enums or traits that do not require guest callbacks. Start with internal asset job support but keep the lane generic enough for memcard/FS later.

Files: new module under prometeu-system service layer.

Step 3 - Implement Serial Worker

What: Implement one worker loop that takes one pending job and runs it to completion or cooperative cancellation.

How: Use a fixed worker thread on host builds. Preserve a logical-lane API so future hardware can map it to a dedicated core.

Files: async lane module; lifecycle wiring in VM runtime service setup.

Step 4 - Implement Shutdown

What: Add explicit stop/shutdown behavior.

How: Wake the lane, stop accepting new jobs, report pending jobs as canceled or shutdown-discarded, and join the worker with bounded behavior.

Files: async lane module and VM runtime lifecycle modules.

Step 5 - Expose Internal Telemetry

What: Add counters for pending depth, active job, submitted, completed, failed, canceled, and superseded.

How: Use cheap atomics or lane-owned state snapshots. Do not update expensive percentile data inside inner decode loops.

Files: async lane module; telemetry structs where runtime telemetry lives.

Criterios de Aceite

• Lane has one active job maximum.
• Lane is separate from render worker code.
• Lane can be started and stopped deterministically.
• Pending jobs are observable.
• Cooperative cancellation can be signaled.
• No guest callback path is introduced.

Tests / Validacao

• Unit tests for enqueue, single active execution, ordering, cancellation signal, and shutdown.
• Concurrency tests must synchronize on real state transitions, not sleeps.
• Run targeted cargo test for the owning crate.

Riscos

• Accidentally creating a generic pool instead of a serial lane.
• Coupling the lane to desktop host thread details.
• Reusing render worker handoff semantics where ordered backlog is required.