parity: add LCOW HCS document parity tests

Adds test infrastructure to validate that the v2 LCOW document builder
(lcow.BuildSandboxConfig) produces the same HCS ComputeSystem documents
as the legacy shim pipeline.

Both paths receive identical inputs (annotations, shim options, devices):

  Legacy: OCI spec → oci.UpdateSpecFromOptions → oci.ProcessAnnotations
    → oci.SpecToUVMCreateOpts → uvm.MakeLCOWDocument

  V2: vm.Spec → lcow.BuildSandboxConfig

Documents are normalized (GUID map keys sorted, owner zeroed,
nil-vs-empty-struct equalized) and compared with go-cmp.

Changes:
- internal/uvm: export MakeLCOWDocument() to generate HCS document
  without creating a VM. Supports both non-SNP and SNP paths.
- test/parity: new package with separated concerns:
  - doc.go: package docs with pipeline diagrams and run instructions
  - helpers_test.go: boot file setup, normalization, JSON logging
  - legacy_pipeline_test.go: wires the 4-step legacy pipeline
  - v2_pipeline_test.go: wraps BuildSandboxConfig
  - lcow_doc_test.go: 3 document parity tests + 5 field parity checks

All 8 tests pass on Windows with Hyper-V + admin privileges.

Signed-off-by: Shreyansh Sancheti <shsancheti@microsoft.com>

Author: Shreyansh Sancheti

internal/uvm/create_lcow.go

@@ -876,6 +876,58 @@ func makeLCOWDoc(ctx context.Context, opts *OptionsLCOW, uvm *UtilityVM) (_ *hcs
 	return doc, nil
 }
 
+// MakeLCOWDocument generates the HCS compute system document for an LCOW VM
+// without actually creating the VM or submitting to HCS. This is useful for
+// parity testing between the legacy and v2 shim document builders.
+//
+// It mirrors the initialization logic of CreateLCOW (UtilityVM struct setup,
+// SCSI controller adjustment, option verification) then calls makeLCOWDoc
+// or makeLCOWSecurityDoc to produce the document depending on whether
+// SecurityPolicyEnabled is set.
+func MakeLCOWDocument(ctx context.Context, opts *OptionsLCOW) (*hcsschema.ComputeSystem, error) {
+	if opts.ID == "" {
+		g, err := guid.NewV4()
+		if err != nil {
+			return nil, err
+		}
+		opts.ID = g.String()
+	}
+
+	if opts.OutputHandlerCreator == nil {
+		opts.OutputHandlerCreator = vmutils.ParseGCSLogrus
+	}
+
+	uvm := &UtilityVM{
+		id:                      opts.ID,
+		owner:                   opts.Owner,
+		operatingSystem:         "linux",
+		scsiControllerCount:     opts.SCSIControllerCount,
+		vpmemMaxCount:           opts.VPMemDeviceCount,
+		vpmemMaxSizeBytes:       opts.VPMemSizeBytes,
+		vpciDevices:             make(map[VPCIDeviceID]*VPCIDevice),
+		physicallyBacked:        !opts.AllowOvercommit,
+		devicesPhysicallyBacked: opts.FullyPhysicallyBacked,
+		createOpts:              opts,
+		vpmemMultiMapping:       !opts.VPMemNoMultiMapping,
+		encryptScratch:          opts.EnableScratchEncryption,
+		noWritableFileShares:    opts.NoWritableFileShares,
+		policyBasedRouting:      opts.PolicyBasedRouting,
+	}
+
+	if osversion.Build() >= osversion.RS5 && uvm.vpmemMaxCount == 0 {
+		uvm.scsiControllerCount = 4
+	}
+
+	if err := verifyOptions(ctx, opts); err != nil {
+		return nil, errors.Wrap(err, errBadUVMOpts.Error())
+	}
+
+	if opts.SecurityPolicyEnabled {
+		return makeLCOWSecurityDoc(ctx, opts, uvm)
+	}
+	return makeLCOWDoc(ctx, opts, uvm)
+}
+
 // CreateLCOW creates an HCS compute system representing a utility VM. It
 // consumes a set of options derived from various defaults and options
 // expressed as annotations.

test/parity/doc.go

@@ -0,0 +1,41 @@
+//go:build windows
+
+// Package parity validates that the v2 LCOW document builder
+// (lcow.BuildSandboxConfig) produces HCS ComputeSystem documents equivalent
+// to the legacy shim pipeline (oci → uvm.MakeLCOWDocument).
+//
+// # How it works
+//
+// Each test case defines a set of annotations, shim options, and devices.
+// These inputs are fed identically to both pipelines:
+//
+//	Legacy: specs.Spec + runhcsopts.Options
+//	  → oci.UpdateSpecFromOptions
+//	  → oci.ProcessAnnotations
+//	  → oci.SpecToUVMCreateOpts → *OptionsLCOW
+//	  → uvm.MakeLCOWDocument → *hcsschema.ComputeSystem
+//
+//	V2: vm.Spec + runhcsopts.Options
+//	  → lcow.BuildSandboxConfig → *hcsschema.ComputeSystem + *SandboxOptions
+//
+// The resulting documents are normalized (random GUID map keys sorted,
+// owner zeroed, nil-vs-empty-struct equalized) then compared with go-cmp.
+//
+// The test also compares legacy OptionsLCOW fields against v2 SandboxOptions
+// to verify configuration semantics are preserved.
+//
+// # File layout
+//
+//	doc.go                    — this file
+//	lcow_doc_test.go          — test cases and input construction (inline)
+//	legacy_pipeline_test.go   — buildLegacyDocument: wires the 4-step legacy pipeline
+//	v2_pipeline_test.go       — buildV2Document: wraps lcow.BuildSandboxConfig
+//	helpers_test.go           — setupBootFiles, normalizeDoc, sorted map helpers, mustJSON
+//
+// # Running
+//
+// Requires: Windows with Hyper-V enabled, admin (elevated) PowerShell.
+//
+//	cd test
+//	go test -tags functional -v -count=1 ./parity/
+package parity

test/parity/helpers_test.go

@@ -0,0 +1,106 @@
+//go:build windows && functional
+
+package parity
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sort"
+	"testing"
+
+	hcsschema "github.com/Microsoft/hcsshim/internal/hcs/schema2"
+	"github.com/Microsoft/hcsshim/internal/vm/vmutils"
+)
+
+// setupBootFiles creates a temp directory with the dummy boot files that both
+// builders probe for when resolving kernel and rootfs paths.
+func setupBootFiles(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	for _, name := range []string{
+		vmutils.KernelFile,
+		vmutils.UncompressedKernelFile,
+		vmutils.InitrdFile,
+		vmutils.VhdFile,
+	} {
+		if err := os.WriteFile(filepath.Join(dir, name), []byte("test"), 0644); err != nil {
+			t.Fatalf("failed to create boot file %s: %v", name, err)
+		}
+	}
+	return dir
+}
+
+// normalizeDoc makes both documents comparable by zeroing nondeterministic
+// fields.
+func normalizeDoc(doc *hcsschema.ComputeSystem) {
+	if doc == nil {
+		return
+	}
+	doc.Owner = ""
+
+	vm := doc.VirtualMachine
+	if vm == nil {
+		return
+	}
+
+	// Empty StorageQoS is the same as nil (no QoS configured).
+	if vm.StorageQoS != nil && vm.StorageQoS.IopsMaximum == 0 && vm.StorageQoS.BandwidthMaximum == 0 {
+		vm.StorageQoS = nil
+	}
+
+	// Empty CpuGroup is the same as nil (no CPU group assigned).
+	if vm.ComputeTopology != nil && vm.ComputeTopology.Processor != nil {
+		if cg := vm.ComputeTopology.Processor.CpuGroup; cg != nil && cg.Id == "" {
+			vm.ComputeTopology.Processor.CpuGroup = nil
+		}
+	}
+
+	if vm.Devices == nil {
+		return
+	}
+
+	// SCSI and vPCI maps use random GUID keys. Sort and re-index for
+	// deterministic comparison.
+	if scsi := vm.Devices.Scsi; scsi != nil {
+		vm.Devices.Scsi = sortedMapKeys(scsi)
+	}
+	if vpci := vm.Devices.VirtualPci; vpci != nil {
+		vm.Devices.VirtualPci = sortedVPCIKeys(vpci)
+	}
+}
+
+func sortedMapKeys(m map[string]hcsschema.Scsi) map[string]hcsschema.Scsi {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	out := make(map[string]hcsschema.Scsi, len(m))
+	for i, k := range keys {
+		out[string(rune('0'+i))] = m[k]
+	}
+	return out
+}
+
+func sortedVPCIKeys(m map[string]hcsschema.VirtualPciDevice) map[string]hcsschema.VirtualPciDevice {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	out := make(map[string]hcsschema.VirtualPciDevice, len(m))
+	for i, k := range keys {
+		out[string(rune('0'+i))] = m[k]
+	}
+	return out
+}
+
+// mustJSON returns indented JSON for logging.
+func mustJSON(v interface{}) string {
+	b, err := json.MarshalIndent(v, "", "  ")
+	if err != nil {
+		panic(err)
+	}
+	return string(b)
+}

test/parity/lcow_doc_test.go

@@ -0,0 +1,171 @@
+//go:build windows && functional
+
+package parity
+
+import (
+	"context"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/opencontainers/runtime-spec/specs-go"
+
+	runhcsopts "github.com/Microsoft/hcsshim/cmd/containerd-shim-runhcs-v1/options"
+	shimannotations "github.com/Microsoft/hcsshim/pkg/annotations"
+	vm "github.com/Microsoft/hcsshim/sandbox-spec/vm/v2"
+)
+
+// TestLCOWDocumentParity feeds identical inputs to both the legacy and v2
+// pipelines and verifies the resulting HCS documents match.
+func TestLCOWDocumentParity(t *testing.T) {
+	t.Parallel()
+	bootDir := setupBootFiles(t)
+
+	tests := []struct {
+		name        string
+		annotations map[string]string          // applied to both pipelines
+		devices     []specs.WindowsDevice      // vPCI devices for both pipelines
+		shimOpts    func() *runhcsopts.Options // nil = use default
+	}{
+		{
+			name: "default config",
+		},
+		{
+			name: "custom CPU and memory",
+			annotations: map[string]string{
+				shimannotations.ProcessorCount: "2",
+				shimannotations.MemorySizeInMB: "2048",
+			},
+		},
+		{
+			name: "storage QoS",
+			annotations: map[string]string{
+				shimannotations.StorageQoSIopsMaximum:      "5000",
+				shimannotations.StorageQoSBandwidthMaximum: "1000000",
+			},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			ctx := context.Background()
+
+			// Shim options — identical for both paths.
+			shimOpts := &runhcsopts.Options{
+				SandboxPlatform:   "linux/amd64",
+				BootFilesRootPath: bootDir,
+			}
+			if tc.shimOpts != nil {
+				shimOpts = tc.shimOpts()
+			}
+
+			// --- Legacy path ---
+			// Build OCI spec with annotations and devices, then run the full
+			// old shim pipeline: UpdateSpecFromOptions → ProcessAnnotations →
+			// SpecToUVMCreateOpts → MakeLCOWDocument.
+			legacySpec := specs.Spec{
+				Annotations: make(map[string]string),
+				Linux:       &specs.Linux{},
+				Windows: &specs.Windows{
+					HyperV:  &specs.WindowsHyperV{},
+					Devices: tc.devices,
+				},
+			}
+			for k, v := range tc.annotations {
+				legacySpec.Annotations[k] = v
+			}
+			legacyDoc, legacyOpts, err := buildLegacyDocument(ctx, legacySpec, shimOpts, bootDir)
+			if err != nil {
+				t.Fatalf("legacy: %v", err)
+			}
+
+			// --- V2 path ---
+			// Build vm.Spec with the same annotations and devices, then call
+			// the v2 builder: BuildSandboxConfig.
+			v2Spec := &vm.Spec{
+				Annotations: make(map[string]string),
+				Devices:     tc.devices,
+			}
+			for k, v := range tc.annotations {
+				v2Spec.Annotations[k] = v
+			}
+			v2Doc, sandboxOpts, err := buildV2Document(ctx, shimOpts, v2Spec, bootDir)
+			if err != nil {
+				t.Fatalf("v2: %v", err)
+			}
+
+			// Log both config structs side by side.
+			t.Logf("Legacy opts: AllowOvercommit=%v PhysicallyBacked=%v ScratchEncrypt=%v "+
+				"NoWriteShares=%v PolicyRouting=%v VPMemNoMultiMap=%v",
+				legacyOpts.AllowOvercommit, legacyOpts.FullyPhysicallyBacked,
+				legacyOpts.EnableScratchEncryption, legacyOpts.NoWritableFileShares,
+				legacyOpts.PolicyBasedRouting, legacyOpts.VPMemNoMultiMapping)
+			t.Logf("V2 sandbox:  PhysicallyBacked=%v ScratchEncrypt=%v "+
+				"NoWriteShares=%v PolicyRouting=%v VPMEMMultiMap=%v Arch=%s",
+				sandboxOpts.FullyPhysicallyBacked, sandboxOpts.EnableScratchEncryption,
+				sandboxOpts.NoWritableFileShares, sandboxOpts.PolicyBasedRouting,
+				sandboxOpts.VPMEMMultiMapping, sandboxOpts.Architecture)
+
+			// Normalize and compare.
+			normalizeDoc(legacyDoc)
+			normalizeDoc(v2Doc)
+
+			if diff := cmp.Diff(legacyDoc, v2Doc); diff != "" {
+				t.Logf("Legacy doc:\n%s", mustJSON(legacyDoc))
+				t.Logf("V2 doc:\n%s", mustJSON(v2Doc))
+				t.Errorf("Document mismatch (-legacy +v2):\n%s", diff)
+			}
+		})
+	}
+}
+
+// TestSandboxOptionsFieldParity verifies that config fields match between
+// legacy OptionsLCOW and v2 SandboxOptions for default inputs.
+func TestSandboxOptionsFieldParity(t *testing.T) {
+	t.Parallel()
+	bootDir := setupBootFiles(t)
+	ctx := context.Background()
+
+	shimOpts := &runhcsopts.Options{
+		SandboxPlatform:   "linux/amd64",
+		BootFilesRootPath: bootDir,
+	}
+
+	// Legacy: build OCI spec inline, run pipeline.
+	legacySpec := specs.Spec{
+		Annotations: map[string]string{},
+		Linux:       &specs.Linux{},
+		Windows:     &specs.Windows{HyperV: &specs.WindowsHyperV{}},
+	}
+	_, legacyOpts, err := buildLegacyDocument(ctx, legacySpec, shimOpts, bootDir)
+	if err != nil {
+		t.Fatalf("legacy: %v", err)
+	}
+
+	// V2: build vm.Spec inline, run builder.
+	v2Spec := &vm.Spec{Annotations: map[string]string{}}
+	_, sandboxOpts, err := buildV2Document(ctx, shimOpts, v2Spec, bootDir)
+	if err != nil {
+		t.Fatalf("v2: %v", err)
+	}
+
+	checks := []struct {
+		name   string
+		legacy interface{}
+		v2     interface{}
+	}{
+		{"NoWritableFileShares", legacyOpts.NoWritableFileShares, sandboxOpts.NoWritableFileShares},
+		{"EnableScratchEncryption", legacyOpts.EnableScratchEncryption, sandboxOpts.EnableScratchEncryption},
+		{"PolicyBasedRouting", legacyOpts.PolicyBasedRouting, sandboxOpts.PolicyBasedRouting},
+		{"FullyPhysicallyBacked", legacyOpts.FullyPhysicallyBacked, sandboxOpts.FullyPhysicallyBacked},
+		{"VPMEMMultiMapping", !legacyOpts.VPMemNoMultiMapping, sandboxOpts.VPMEMMultiMapping},
+	}
+
+	for _, c := range checks {
+		t.Run(c.name, func(t *testing.T) {
+			if c.legacy != c.v2 {
+				t.Errorf("%s mismatch: legacy=%v v2=%v", c.name, c.legacy, c.v2)
+			}
+		})
+	}
+}