---
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.