prometeu-runtime/discussion/workflow/plans/PLN-0127-async-lane-memcard-and-fs-integration-boundaries.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0127	perf-async-background-work-lanes-for-assets-and-fs	Async Lane Memcard and FS Integration Boundaries	open	2026-06-28		DEC-0034	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:

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.