119 lines
3.8 KiB
Markdown
119 lines
3.8 KiB
Markdown
---
|
|
id: PLN-0123
|
|
ticket: perf-async-background-work-lanes-for-assets-and-fs
|
|
title: Async Work Lane Specification Propagation
|
|
status: done
|
|
created: 2026-06-28
|
|
completed:
|
|
ref_decisions: [DEC-0034]
|
|
tags: [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`.
|