Layer 7: Virtual File System

// Direct file writes
fs.writeFileSync('package.json', newContent);  // ← Can corrupt!
fs.writeFileSync('tsconfig.json', newContent); // ← If this fails, partial state!

// All operations in memory
vfs.writeFile('package.json', newContent);
vfs.writeFile('tsconfig.json', newContent);
 
// Atomic commit
await vfs.flushToDisk();  // All or nothing

src/core/services/file-system/file-engine/virtual-file-system.ts

export class VirtualFileSystem {
  private files: Map<string, string>;  // path → content
  private baseDir: string;
  private blueprintId: string;
 
  constructor(blueprintId: string, baseDir: string) {
    this.blueprintId = blueprintId;
    this.baseDir = baseDir;
    this.files = new Map();
  }
 
  // In-memory operations
  writeFile(path: string, content: string): void {
    this.files.set(path, content);
  }
 
  readFile(path: string): string | null {
    return this.files.get(path) || null;
  }
 
  fileExists(path: string): boolean {
    return this.files.has(path);
  }
 
  // Disk operations
  async initializeWithFiles(filePaths: string[]): Promise<void> {
    // Pre-populate VFS from disk
  }
 
  async flushToDisk(): Promise<void> {
    // Atomic write to disk
  }
}

// Orchestrator creates VFS per blueprint
const vfs = new VirtualFileSystem(
  `blueprint-${blueprint.id}`,
  projectRoot
);

// Executor analyzes blueprint
const analysis = blueprintAnalyzer.analyzeBlueprint(blueprint);
 
// Pre-load files from disk into VFS
await vfs.initializeWithFiles(analysis.filesToRead);

// Blueprint will enhance layout.tsx
analysis.filesToRead = ['src/app/layout.tsx'];
 
// VFS pre-populated:
vfs.files = new Map([
  ['src/app/layout.tsx', '... actual file content from disk ...']
]);

// CREATE_FILE
vfs.writeFile('src/new-file.ts', content);
 
// ENHANCE_FILE (reads from VFS, writes to VFS)
const existing = vfs.readFile('package.json');
const modified = merge(existing, newData);
vfs.writeFile('package.json', modified);

// After blueprint succeeds
if (executionResult.success) {
  await vfs.flushToDisk();
}

async flushToDisk(): Promise<void> {
  try {
    // Write all files atomically
    for (const [relativePath, content] of this.files.entries()) {
      const fullPath = join(this.baseDir, relativePath);
      
      // Ensure directory exists
      await fs.promises.mkdir(dirname(fullPath), { recursive: true });
      
      // Write file
      await fs.promises.writeFile(fullPath, content, 'utf-8');
    }
    
    logger.info(`✅ VFS flushed: ${this.files.size} files written`);
  } catch (error) {
    throw new ArchitechError(
      ArchitechErrorCode.VFS_FLUSH_FAILED,
      `Failed to flush VFS to disk: ${error.message}`
    );
  }
}

// After flush, VFS can be garbage collected
// Orchestrator creates new VFS for next blueprint

{
  type: 'ENHANCE_FILE',
  path: 'src/app/layout.tsx',
  modifier: 'jsx-children-wrapper',
  params: { wrapperComponent: 'QueryProvider' }
}

// src/core/services/execution/blueprint/blueprint-executor.ts
async executeBlueprint(blueprint: Blueprint, context, vfs: VirtualFileSystem) {
  // 1. Analyze blueprint
  const analysis = this.blueprintAnalyzer.analyzeBlueprint(blueprint, context);
  
  // 2. Pre-populate VFS
  if (analysis.filesToRead.length > 0) {
    await vfs.initializeWithFiles(analysis.filesToRead);
  }
  
  // 3. Execute actions (they find their files in VFS)
  for (const action of blueprint.actions) {
    await this.executeAction(action, vfs);
  }
}

// Read file from VFS
const content = vfs.readFile('package.json');
 
// If not in VFS, returns null (not disk read!)

// Write to VFS (in-memory)
vfs.writeFile('src/new-file.ts', content);
 
// File stored in Map, not on disk
this.files.set('src/new-file.ts', content);

// Check if file exists in VFS
if (vfs.fileExists('src/app/layout.tsx')) {
  // File was pre-loaded or created in this VFS
}

// VFS automatically creates directories on flush
vfs.writeFile('deeply/nested/file.ts', content);
 
// On flush, creates:
// - deeply/
// - deeply/nested/
// - deeply/nested/file.ts

try {
  vfs.writeFile('file1.ts', content1);
  vfs.writeFile('file2.ts', content2);
  await vfs.flushToDisk();  // Atomic
} catch (error) {
  // If flush fails, disk unchanged
  // No file1.ts on disk, no file2.ts on disk
}

// Blueprint A's VFS
const vfsA = new VirtualFileSystem('blueprint-A', root);
vfsA.writeFile('config.ts', 'A content');
 
// Blueprint B's VFS (different instance)
const vfsB = new VirtualFileSystem('blueprint-B', root);
vfsB.readFile('config.ts');  // Returns null (not in this VFS)

const vfs = new VirtualFileSystem(...);
 
try {
  await executeBlueprint(blueprint, vfs);
  await vfs.flushToDisk();  // ← Never reached if blueprint fails
} catch (error) {
  // VFS discarded
  // Disk unchanged
  // No cleanup needed
}

// Blueprint A creates file
vfsA.writeFile('config.ts', 'export const foo = 1;');
await vfsA.flushToDisk();
 
// Blueprint B can't read it (different VFS)
const content = vfsB.readFile('config.ts');  // null (not in this VFS)

// 1. Create VFS
const vfs = new VirtualFileSystem('my-blueprint', './project');
 
// 2. Pre-populate with existing files
await vfs.initializeWithFiles(['package.json', 'tsconfig.json']);
 
// 3. Read existing content
const pkgJson = JSON.parse(vfs.readFile('package.json'));
 
// 4. Modify in memory
pkgJson.dependencies['new-package'] = '^1.0.0';
 
// 5. Write back to VFS
vfs.writeFile('package.json', JSON.stringify(pkgJson, null, 2));
 
// 6. Create new file in VFS
vfs.writeFile('src/new-file.ts', 'export const foo = 1;');
 
// 7. Atomic flush to disk
await vfs.flushToDisk();
 
// Disk now has:
// - package.json (modified)
// - src/new-file.ts (new)
// All atomic!

fs.writeFileSync('file1.ts', content1);
fs.writeFileSync('file2.ts', content2);  // ← Fails!
// file1.ts on disk, file2.ts missing → PARTIAL STATE

vfs.writeFile('file1.ts', content1);
vfs.writeFile('file2.ts', content2);
await vfs.flushToDisk();  // ← Fails! But disk unchanged

enum ArchitechErrorCode {
  VFS_FLUSH_FAILED,
  BLUEPRINT_EXECUTION_FAILED,
  MODULE_NOT_FOUND,
  DEPENDENCY_CONFLICT,
  FILE_MODIFICATION_FAILED,
  TEMPLATE_RENDERING_FAILED,
  VALIDATION_FAILED
}

class ArchitechError extends Error {
  code: ArchitechErrorCode;
  context: ErrorContext;
  recoverable: boolean;
  recoverySuggestion?: string;
  
  getUserMessage(): string {
    return `${this.message}\n\n💡 ${this.recoverySuggestion}`;
  }
}

// Blueprint execution with automatic rollback
async function executeBlueprint(blueprint, vfs) {
  try {
    // 1. Pre-populate VFS from disk
    await vfs.initializeWithFiles(filesToRead);
    
    // 2. Execute all actions (in-memory)
    for (const action of blueprint.actions) {
      await executeAction(action, vfs);  // May throw error
    }
    
    // 3. Validate result
    const validation = validateExecution(vfs);
    if (!validation.success) {
      throw new ArchitechError(
        ArchitechErrorCode.VALIDATION_FAILED,
        validation.error
      );
    }
    
    // 4. Flush to disk (atomic)
    await vfs.flushToDisk();  // ← Only reached if everything succeeds
    
    return { success: true };
    
  } catch (error) {
    // VFS automatically discarded
    // Zero disk changes
    // Project remains clean
    
    console.error(`❌ Blueprint failed: ${error.message}`);
    if (error.recoverySuggestion) {
      console.log(`\n💡 Suggestion: ${error.recoverySuggestion}`);
    }
    
    return { success: false, error };
  }
}

❌ Error: Module 'database/drizzle' not found
 
💡 Recovery Suggestions:
1. Check spelling - did you mean 'database/drizzle-orm'?
2. Run 'architech marketplace' to browse available modules
3. Ensure marketplace package is installed: npm install @architech/marketplace

❌ Error: Connector 'drizzle-nextjs' requires capability 'database'
 
💡 Recovery Suggestions:
1. Install database adapter first:
   architech add adapter drizzle
2. Or use a different connector that doesn't require a database
3. Check your genome configuration for missing adapters

❌ Error: Failed to write file 'src/app/layout.tsx'
Reason: Permission denied
 
💡 Recovery Suggestions:
1. Check file permissions in target directory
2. Ensure directory is writable: chmod +w src/app/
3. Try running with sudo (not recommended) or fix ownership
 
🛡️ Safety: No files were modified (VFS rollback successful)

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

for (const blueprint of blueprints) {
  const vfs = new VirtualFileSystem(...);  // New VFS
  await execute(blueprint, vfs);
  await vfs.flushToDisk();  // Flush immediately
}