121 lines
3.5 KiB
Markdown
121 lines
3.5 KiB
Markdown
---
|
|
id: PLN-0127
|
|
ticket: perf-async-background-work-lanes-for-assets-and-fs
|
|
title: Async Lane Memcard and FS Integration Boundaries
|
|
status: done
|
|
created: 2026-06-28
|
|
completed:
|
|
ref_decisions: [DEC-0034]
|
|
tags: [perf, fs, memcard, async, runtime]
|
|
---
|
|
|
|
# PLN-0127 - Async Lane Memcard and FS Integration Boundaries
|
|
|
|
## Briefing
|
|
|
|
`DEC-0034` allows memcard and FS work to consume the async IO lane but keeps
|
|
public FS API semantics out of scope. This plan establishes integration
|
|
boundaries without deciding app-home FS API shape.
|
|
|
|
## Decisions de Origem
|
|
|
|
- `DEC-0034` - Async Work Lane and Asset Backlog Contract.
|
|
|
|
## Alvo
|
|
|
|
Define and implement safe internal boundaries for memcard and FS use of the
|
|
async work lane, preserving lane priority and keeping FS public API decisions in
|
|
`AGD-0006`.
|
|
|
|
## Escopo
|
|
|
|
Included:
|
|
|
|
- Memcard as a priority lane consumer candidate.
|
|
- FS as a permitted internal lane consumer.
|
|
- Priority ordering in the lane.
|
|
- Updates to `AGD-0006` to acknowledge the lane.
|
|
|
|
Fora de Escopo:
|
|
|
|
- Public FS request/poll design.
|
|
- App-home path/status contract.
|
|
- Full memcard async conversion if it requires public ABI changes.
|
|
|
|
## Plano de Execucao
|
|
|
|
### Step 1 - Update FS Agenda
|
|
|
|
**What:** Record that an async IO lane exists and may be used by FS.
|
|
|
|
**How:** Add a concise section to `AGD-0006` stating that FS public API remains
|
|
owned by that agenda, but implementation may use the async lane from `DEC-0034`.
|
|
|
|
**Files:** `discussion/workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md`.
|
|
|
|
### Step 2 - Identify Memcard Operations
|
|
|
|
**What:** List memcard operations that can benefit from async IO.
|
|
|
|
**How:** Inspect `crates/console/prometeu-system/src/services/memcard.rs` and
|
|
VM runtime dispatch for `mem.*` operations. Classify read, write, commit, and
|
|
clear behavior.
|
|
|
|
**Files:** memcard service and VM runtime dispatch modules.
|
|
|
|
### Step 3 - Define Lane Priority
|
|
|
|
**What:** Encode the initial priority order from `DEC-0034`.
|
|
|
|
**How:** Add priority classes:
|
|
|
|
```text
|
|
memcard commit/write
|
|
FS write/config
|
|
asset load
|
|
non-critical list/read
|
|
```
|
|
|
|
**Files:** async lane module from `PLN-0124`.
|
|
|
|
### Step 4 - Add Internal Consumer Hooks
|
|
|
|
**What:** Provide internal APIs for memcard/FS to submit lane jobs later.
|
|
|
|
**How:** Add types/interfaces without changing public FS syscall behavior.
|
|
No public FS request/poll operations are introduced here.
|
|
|
|
**Files:** async lane module; FS/memcard service modules as needed.
|
|
|
|
### Step 5 - Preserve Current Public Behavior
|
|
|
|
**What:** Ensure existing memcard and FS syscalls keep their current observable
|
|
surface unless a later plan explicitly changes it.
|
|
|
|
**How:** Do not alter return shapes in this plan. Add tests proving existing
|
|
status-first behavior remains intact.
|
|
|
|
**Files:** VM runtime FS/memcard tests.
|
|
|
|
## Criterios de Aceite
|
|
|
|
- [ ] `AGD-0006` acknowledges the async IO lane and keeps FS public API in its
|
|
own scope.
|
|
- [ ] Async lane supports priority classes required by `DEC-0034`.
|
|
- [ ] Memcard and FS can be represented as internal lane consumers.
|
|
- [ ] Existing public memcard/FS syscall shapes are unchanged.
|
|
- [ ] No FS public request/poll API is introduced by this plan.
|
|
|
|
## Tests / Validacao
|
|
|
|
- Existing FS/memcard tests continue passing.
|
|
- Unit tests for lane priority ordering.
|
|
- Tests proving asset jobs do not overlap with higher-priority memcard jobs
|
|
once both are submitted through the lane.
|
|
|
|
## Riscos
|
|
|
|
- Accidentally deciding FS public API in the wrong discussion.
|
|
- Making memcard async in a way that changes status-first behavior.
|
|
- Starving asset loads if priority rules do not include fairness.
|