DRIVERS-3300: Implement returnStoredSource in $vectorSearch

[paulinevos]

Depends on mongodb/mql-specifications#38

Fixes PHPLIB-1763

[Copilot]

Pull request overview

Implements support for the returnStoredSource option on the $vectorSearch aggregation stage within the PHP builder, aligning stage construction and encoding with the updated spec and adding coverage for the new option.

Changes:

• Added returnStoredSource as an optional boolean argument/property for $vectorSearch stage encoding.
• Updated the stage factory and fluent factory helpers to accept/pass through returnStoredSource.
• Added a new pipeline fixture and test case validating returnStoredSource: true output.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/Builder/Stage/VectorSearchStageTest.php	Adds a new test covering $vectorSearch with returnStoredSource: true.
tests/Builder/Stage/Pipelines.php	Updates vector search doc links and adds a stored-source pipeline fixture.
src/Builder/Stage/VectorSearchStage.php	Extends the stage operator to include and serialize returnStoredSource.
src/Builder/Stage/FluentFactoryTrait.php	Adds returnStoredSource to the fluent vectorSearch() helper and forwards it.
src/Builder/Stage/FactoryTrait.php	Adds returnStoredSource to the static vectorSearch() factory and forwards it.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 66.66667% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 87.69%. Comparing base (2628950) to head (98b0ea3).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/Builder/Stage/FluentFactoryTrait.php	0.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               v2.x    #1896      +/-   ##
============================================
- Coverage     87.72%   87.69%   -0.03%     
  Complexity     3328     3328              
============================================
  Files           454      454              
  Lines          6656     6657       +1     
============================================
- Hits           5839     5838       -1     
- Misses          817      819       +2     

Flag	Coverage Δ
6.0-replica_set	86.57% <66.66%> (+<0.01%)	⬆️
6.0-server	82.61% <66.66%> (+<0.01%)	⬆️
6.0-sharded_cluster	?
8.0-replica_set	87.59% <66.66%> (+<0.01%)	⬆️
8.0-server	83.35% <66.66%> (+<0.01%)	⬆️
8.0-sharded_cluster	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.