[Refactoring] Split src/cloud-hypervisor/cleanup-registry.ts into focused modules #8513

Refactoring Opportunity

Summary

• File: src/cloud-hypervisor/cleanup-registry.ts
• Current size: 870 lines
• Responsibilities identified: 4 distinct concerns inside one DurableCloudHypervisorCleanupRegistry class

Evidence

The single class (lines 131–850) owns:

1. Network resource cleanup — deleteNetwork, validateRecordResources (lines 307–384)
2. VMM identity/ACL cleanup — deleteVmmIdentity (lines 385–481, 97 lines — the longest method in the file), captureVmmIdentity/prepareVmmAcl/releaseVmmAcl interface methods
3. Process lifecycle cleanup — stopProcess, captureProcessIdentity, processMatches (lines 482–572)
4. Virtiofsd mount/record persistence — unmountVirtiofsdResources, readMounts, assertNoMountsUnder, readRecord, writeRecord, ensureRegistryDirectory (lines 508–664)

This registry is the durable safety net that prevents leaked network namespaces, cgroups, and VMM processes across crashes/restarts (per its cleanup-record persistence design), so it is security/resource-isolation-critical. deleteVmmIdentity alone is 97 lines, exceeding the 80-line long-function heuristic, and mixes ACL release with identity verification before deletion.

Proposed Split

src/cloud-hypervisor/cleanup-registry.ts (870 lines) could be split into:

• src/cloud-hypervisor/cleanup-registry.ts — orchestration facade (create, createPending, reapPending, record read/write dispatch) implementing CloudHypervisorCleanupRegistry (~250 lines)
• src/cloud-hypervisor/cleanup-network.ts — deleteNetwork, validateRecordResources, captureInterfaceIdentity/interfaceExists (~150 lines)
• src/cloud-hypervisor/cleanup-vmm-identity.ts — deleteVmmIdentity and ACL prepare/release logic (~150 lines)
• src/cloud-hypervisor/cleanup-process.ts — stopProcess, captureProcessIdentity, processMatches (~120 lines)
• src/cloud-hypervisor/cleanup-record-store.ts — readRecord/writeRecord/ensureRegistryDirectory/virtiofsd mount checks (~150 lines)

Affected Callers

src/cloud-hypervisor/cleanup-identity.test.ts
src/cloud-hypervisor/cleanup-registry.test.ts
src/cloud-hypervisor/cleanup-registry.test-utils.ts
src/cloud-hypervisor/cleanup-handle.test.ts
src/cloud-hypervisor/cleanup-process.test.ts
src/cloud-hypervisor/virtiofsd.ts
src/cloud-hypervisor/manager.ts
src/cloud-hypervisor/manager-start.ts
src/cloud-hypervisor/manager-virtiofsd.test.ts
src/cloud-hypervisor/cleanup-handle.ts
src/cloud-hypervisor/virtiofsd.test.ts
src/cloud-hypervisor/manager-types.ts
src/cloud-hypervisor/manager-cleanup.test.ts
src/cloud-hypervisor/manager-launch.test.ts
src/cloud-hypervisor/manager-stop.ts
src/cloud-hypervisor/manager.test-utils.ts

Note the existing test suite is already split by concern (cleanup-identity.test.ts, cleanup-process.test.ts, cleanup-handle.test.ts), which suggests the tests already anticipate this module boundary even though the implementation is still one file. The split can keep DurableCloudHypervisorCleanupRegistry as the exported class name, re-exporting from the facade so none of the 16 callers need import-path changes.

Effort Estimate

Medium-High (many test files exercise this class; splitting requires care to keep shared private state, e.g. cgroup/process maps, accessible across the new modules — likely via composition rather than free functions)

Benefits

• Aligns implementation module boundaries with the already-split test file structure
• Isolates VMM identity/ACL cleanup (highest-risk, longest method) for focused security review
• Reduces blast radius when modifying one cleanup concern (e.g. virtiofsd unmounting) without touching network/process cleanup code

Detected by Refactoring Scanner workflow. Run date: 2026-09-13

Generated by Refactoring Opportunity Scanner · copilot · auto · 95.2 AIC · ⊞ 10.4K · ◷

• expires on Nov 12, 2026, 3:06 PM UTC