Per-Blueprint VFS

Decision: One VFS per Blueprint

The Decision

Each blueprint receives its own dedicated VirtualFileSystem instance.

for (const blueprint of blueprints) {
  const vfs = new VirtualFileSystem(`blueprint-${blueprint.id}`, projectRoot);
  await execute(blueprint, vfs);
  await vfs.flushToDisk();
}

Rationale

1. Blueprint Isolation

Blueprints cannot interfere with each other's file operations.

2. Atomic Per-Blueprint

Each blueprint is an atomic unit — all changes or none.

3. Targeted Pre-population

Each VFS pre-loaded with only files that specific blueprint needs.

4. Clean Rollback

Blueprint fails → VFS discarded, no cleanup needed.

Alternatives Considered

Shared VFS (Rejected)

// Single VFS for all blueprints
const vfs = new VirtualFileSystem(...);
for (const blueprint of blueprints) {
  await execute(blueprint, vfs);
}
await vfs.flushToDisk();  // One flush at end

Rejected because:

• Blueprints could interfere
• Harder to rollback individual blueprints
• Less clear ownership of files

Trade-offs

Cost: Memory overhead (multiple VFS instances)
Benefit: Safety, isolation, atomicity

Verdict: Safety worth the cost.

Back to Design Decisions →