prometeu-runtime/discussion/workflow/plans/PLN-0123-async-work-lane-specification-propagation.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0123	perf-async-background-work-lanes-for-assets-and-fs	Async Work Lane Specification Propagation	done	2026-06-28		DEC-0034	perf asset fs async scheduler runtime spec

PLN-0123 - Async Work Lane Specification Propagation

Briefing

DEC-0034 establishes a third serial async work lane, asset backlog semantics, stable bank-slot handles, superseding, progress, telemetry, and FS/memcard lane boundaries. The canonical specs must be updated before code work relies on the new contract.

Decisions de Origem

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

Alvo

Publish the accepted async work lane and asset backlog contract in the canonical runtime specs.

Escopo

Included:

• Update asset management spec.
• Update syscall ABI spec if public backlog APIs are named there.
• Update syscall policy/status language for operational asset states.
• Update events/concurrency spec with the async work lane as an implementation lane that does not introduce guest callbacks.
• Add a cross-reference from FS/app-home agenda or notes to the async IO lane.

Fora de Escopo:

• Implementing runtime code.
• Finalizing public FS API semantics.
• Changing render worker contracts.

Plano de Execucao

Step 1 - Update Asset Management

What: Add the third async lane, backlog, handle, superseding, progress, and telemetry contract.

How: Extend docs/specs/runtime/15-asset-management.md around the existing asset.load/status/commit/cancel section. Preserve the existing asset.load(asset_id, slot) identity contract.

Files: docs/specs/runtime/15-asset-management.md.

Step 2 - Update Host ABI

What: Add the backlog API direction if the ABI spec is the canonical place for syscall shapes.

How: Extend the asset surface section with the planned backlog operations, marking exact numeric ids as implementation-plan work if ids are not assigned yet.

Files: docs/specs/runtime/16-host-abi-and-syscalls.md.

Step 3 - Update Syscall Policies

What: Clarify that superseded, canceled, backend_unavailable, and decode failures are operational statuses, not faults.

How: Add asset-domain examples under status-first policy.

Files: docs/specs/runtime/16a-syscall-policies.md.

Step 4 - Update Events and Concurrency

What: Document that the async work lane is an implementation lane.

How: Add a section next to render worker concurrency stating that asset/IO lane work does not introduce guest callbacks or hidden guest execution.

Files: docs/specs/runtime/09-events-and-concurrency.md.

Step 5 - Cross-Reference FS Work

What: Record that FS may consume the async IO lane, while public FS API semantics remain owned by the app-home filesystem discussion.

How: Add a note in AGD-0006 or its future decision input, without deciding FS request/poll shape in this plan.

Files: discussion/workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md.

Criterios de Aceite

• Specs state that the async work lane is serial and separate from render.
• Asset spec states backlog keying by bank_type/slot.
• Asset spec states stable slot handles with slot_state and request_state.
• Asset spec states superseding behavior.
• Asset spec states main-lane commit/install.
• FS is cross-referenced as a permitted lane consumer without public API decisions.

Tests / Validacao

• Run discussion validate.
• Review spec links for broken relative paths.
• No cargo tests are required for this documentation-only plan.

Riscos

• Public ABI names may be refined later; the spec must avoid assigning ids too early if implementation work has not reserved them.
• FS scope can leak into this work; keep FS public API decisions in AGD-0006.