From edb0820a7c920f9b9ffc13910a6f8d59133e953d Mon Sep 17 00:00:00 2001
From: XperiAndri <xperiandri@outlook.com>
Date: Sat, 10 Oct 2026 13:40:45 +0200
Subject: [PATCH 1/2] refactor: return voption and struct tuples from the
 collection functions

FSharp.Core's Seq, List and Array functions that look an element up
return an option, and zip returns reference tuples: one heap object per
result. src/Shared/ValueCollections.fs shadows them with functions of
the same names and meaning that return a voption or struct tuples:
tryHead, tryLast, tryItem, tryExactlyOne, tryFind, tryFindBack,
tryFindIndex, tryFindIndexBack, tryPick, whose chooser returns a voption
too, and zip. Seq.zip is Enumerable.Zip.

Every F# project under src and tests compiles the file first, through
the root Directory.Build.props, and gets an internal copy. The module
opens itself in the namespace FSharp.Azure.Cosmos, so the shadows are in
effect in the code of that namespace and in every file that opens it,
while a function that only FSharp.Core has resolves to it as before. A
file in another namespace opens FSharp.Azure.Cosmos to get them, and so
does one in a child namespace such as FSharp.Azure.Cosmos.Tests: a child
namespace does not open the modules of its parent. The build project is
left out, because its scripts were generated against the functions of
FSharp.Core.

The two places that used such a function follow: the first item of a
feed page in Read.fs and a zip in the ExistsAsync concurrency test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Directory.Build.props                         |  10 +
 src/Cosmos/Read.fs                            |   4 +-
 src/Shared/ValueCollections.fs                | 269 ++++++++++++++++++
 .../FSharp.Azure.Cosmos.Tests.fsproj          |   1 +
 tests/Cosmos.Tests/ReadExtensionsTests.fs     |   2 +-
 tests/Cosmos.Tests/TestCategories.fs          |   8 +
 tests/Cosmos.Tests/ValueCollectionsTests.fs   | 237 +++++++++++++++
 7 files changed, 528 insertions(+), 3 deletions(-)
 create mode 100644 src/Shared/ValueCollections.fs
 create mode 100644 tests/Cosmos.Tests/ValueCollectionsTests.fs

diff --git a/Directory.Build.props b/Directory.Build.props
index c9619ce2..d1cdebeb 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -43,6 +43,16 @@ See https://learn.microsoft.com/en-us/visualstudio/msbuild/customize-by-director
     <PackageReference Include="FSharp.Core" />
   </ItemGroup>
 
+  <!--
+    Every F# project of the library and of its tests compiles the collection helpers first. They shadow the functions
+    of Seq, List and Array that return an option or reference tuples with functions that return a voption or struct
+    tuples, for the code of the namespace FSharp.Azure.Cosmos and for every file that opens it. The build project is
+    left out: its scripts were generated against the functions of FSharp.Core.
+  -->
+  <ItemGroup Condition="'$(MSBuildProjectExtension)' == '.fsproj' And '$(MSBuildProjectName)' != 'build'">
+    <Compile Include="$(MSBuildThisFileDirectory)src/Shared/ValueCollections.fs" Link="Shared/ValueCollections.fs" />
+  </ItemGroup>
+
   <!--<ItemGroup Condition="'$(TargetFramework)' == 'net10.0'">
     <PackageReference Include="BinaryDefense.FSharp.Analyzers.Hashing" PrivateAssets="all" />
     <PackageReference Include="FSharp.Compiler.Service" PrivateAssets="all" />
diff --git a/src/Cosmos/Read.fs b/src/Cosmos/Read.fs
index 75162009..3dd0df38 100644
--- a/src/Cosmos/Read.fs
+++ b/src/Cosmos/Read.fs
@@ -199,8 +199,8 @@ type FeedIteratorExtensions private () =
 
     static let seqToReadResult (items : 'T seq) =
         match items |> Seq.tryHead with
-        | Some item -> Ok item
-        | None -> NotFound "Item not found"
+        | ValueSome item -> Ok item
+        | ValueNone -> NotFound "Item not found"
 
     [<Extension>]
     static member FirstAsync (iterator : FeedIterator<'T>, [<Optional>] cancellationToken : CancellationToken) = task {
diff --git a/src/Shared/ValueCollections.fs b/src/Shared/ValueCollections.fs
new file mode 100644
index 00000000..13f42ba8
--- /dev/null
+++ b/src/Shared/ValueCollections.fs
@@ -0,0 +1,269 @@
+/// <summary>
+/// The functions of <see cref="T:Microsoft.FSharp.Collections.SeqModule"/>,
+/// <see cref="T:Microsoft.FSharp.Collections.ListModule"/> and <see cref="T:Microsoft.FSharp.Collections.ArrayModule"/>
+/// that return an <see cref="T:Microsoft.FSharp.Core.FSharpOption`1"/> or reference tuples, shadowed by functions that
+/// return a <see cref="T:Microsoft.FSharp.Core.FSharpValueOption`1"/> or struct tuples, so that looking an element up or
+/// pairing two collections allocates no object per result.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Every F# project under <c>src</c> and <c>tests</c> compiles this file first, through the root
+/// <c>Directory.Build.props</c>, and gets its own internal copy. The module opens itself in the namespace
+/// <c>FSharp.Azure.Cosmos</c>: the shadows are in effect in the code of that namespace and in every file that opens it.
+/// A file in another namespace needs <c>open FSharp.Azure.Cosmos</c>, and so does one in a child namespace such as
+/// <c>FSharp.Azure.Cosmos.Tests</c>, because a child namespace does not open the modules of its parent.
+/// </para>
+/// <para>
+/// A shadow means what the FSharp.Core function of the same name means, and that function stays reachable by its full
+/// name: <see cref="M:Microsoft.FSharp.Collections.SeqModule.TryHead``1(System.Collections.Generic.IEnumerable{``0})"/>
+/// is written <c>Microsoft.FSharp.Collections.Seq.tryHead</c>. Functions that only FSharp.Core has, such as
+/// <see cref="M:Microsoft.FSharp.Collections.SeqModule.Map``2(Microsoft.FSharp.Core.FSharpFunc{``0,``1},System.Collections.Generic.IEnumerable{``0})"/>,
+/// resolve to FSharp.Core as before. A function that is missing here is added here, not converted at its call site.
+/// </para>
+/// </remarks>
+[<AutoOpen>]
+module internal FSharp.Azure.Cosmos.ValueCollections
+
+open System.Linq
+
+[<RequireQualifiedAccess>]
+module Array =
+
+    /// The first element, or no value when the array is empty.
+    let tryHead (array : 'T array) : 'T voption = if array.Length = 0 then ValueNone else ValueSome array[0]
+
+    /// The last element, or no value when the array is empty.
+    let tryLast (array : 'T array) : 'T voption =
+        if array.Length = 0 then
+            ValueNone
+        else
+            ValueSome array[array.Length - 1]
+
+    /// The element at the index, or no value when the index is outside the array.
+    let tryItem (index : int) (array : 'T array) : 'T voption =
+        if index < 0 || index >= array.Length then
+            ValueNone
+        else
+            ValueSome array[index]
+
+    /// The only element, or no value when the array is empty or has more than one element.
+    let tryExactlyOne (array : 'T array) : 'T voption = if array.Length = 1 then ValueSome array[0] else ValueNone
+
+    /// The index of the first element for which the predicate holds, or no value when it holds for none.
+    let tryFindIndex (predicate : 'T -> bool) (array : 'T array) : int voption =
+        let mutable index = 0
+        let mutable found = ValueNone
+
+        while found.IsNone && index < array.Length do
+            if predicate array[index] then
+                found <- ValueSome index
+
+            index <- index + 1
+
+        found
+
+    /// The index of the last element for which the predicate holds, or no value when it holds for none.
+    let tryFindIndexBack (predicate : 'T -> bool) (array : 'T array) : int voption =
+        let mutable index = array.Length - 1
+        let mutable found = ValueNone
+
+        while found.IsNone && index >= 0 do
+            if predicate array[index] then
+                found <- ValueSome index
+
+            index <- index - 1
+
+        found
+
+    /// The first element for which the predicate holds, or no value when it holds for none.
+    let tryFind (predicate : 'T -> bool) (array : 'T array) : 'T voption =
+        match tryFindIndex predicate array with
+        | ValueSome index -> ValueSome array[index]
+        | ValueNone -> ValueNone
+
+    /// The last element for which the predicate holds, or no value when it holds for none.
+    let tryFindBack (predicate : 'T -> bool) (array : 'T array) : 'T voption =
+        match tryFindIndexBack predicate array with
+        | ValueSome index -> ValueSome array[index]
+        | ValueNone -> ValueNone
+
+    /// The first value that the chooser gives for an element, or no value when it gives none.
+    let tryPick (chooser : 'T -> 'U voption) (array : 'T array) : 'U voption =
+        let mutable index = 0
+        let mutable picked = ValueNone
+
+        while picked.IsNone && index < array.Length do
+            picked <- chooser array[index]
+            index <- index + 1
+
+        picked
+
+    /// The elements of two arrays of the same length, paired by index; arrays of different lengths are an error, as for
+    /// the function of FSharp.Core.
+    let zip (first : 'T1 array) (second : 'T2 array) : struct ('T1 * 'T2) array =
+        Array.map2 (fun left right -> struct (left, right)) first second
+
+[<RequireQualifiedAccess>]
+module List =
+
+    /// The first element, or no value when the list is empty.
+    let tryHead (list : 'T list) : 'T voption =
+        match list with
+        | head :: _ -> ValueSome head
+        | [] -> ValueNone
+
+    /// The last element, or no value when the list is empty.
+    let rec tryLast (list : 'T list) : 'T voption =
+        match list with
+        | [] -> ValueNone
+        | [ last ] -> ValueSome last
+        | _ :: tail -> tryLast tail
+
+    /// The element at the index, or no value when the index is outside the list.
+    let rec tryItem (index : int) (list : 'T list) : 'T voption =
+        match list with
+        | head :: _ when index = 0 -> ValueSome head
+        | _ :: tail when index > 0 -> tryItem (index - 1) tail
+        | _ -> ValueNone
+
+    /// The only element, or no value when the list is empty or has more than one element.
+    let tryExactlyOne (list : 'T list) : 'T voption =
+        match list with
+        | [ only ] -> ValueSome only
+        | _ -> ValueNone
+
+    /// The first element for which the predicate holds, or no value when it holds for none.
+    let rec tryFind (predicate : 'T -> bool) (list : 'T list) : 'T voption =
+        match list with
+        | [] -> ValueNone
+        | head :: _ when predicate head -> ValueSome head
+        | _ :: tail -> tryFind predicate tail
+
+    /// The last element for which the predicate holds, or no value when it holds for none.
+    let tryFindBack (predicate : 'T -> bool) (list : 'T list) : 'T voption = list |> List.toArray |> Array.tryFindBack predicate
+
+    /// The index of the first element for which the predicate holds, or no value when it holds for none.
+    let tryFindIndex (predicate : 'T -> bool) (list : 'T list) : int voption =
+        let rec search index remaining =
+            match remaining with
+            | [] -> ValueNone
+            | head :: _ when predicate head -> ValueSome index
+            | _ :: tail -> search (index + 1) tail
+
+        search 0 list
+
+    /// The index of the last element for which the predicate holds, or no value when it holds for none.
+    let tryFindIndexBack (predicate : 'T -> bool) (list : 'T list) : int voption =
+        list |> List.toArray |> Array.tryFindIndexBack predicate
+
+    /// The first value that the chooser gives for an element, or no value when it gives none.
+    let rec tryPick (chooser : 'T -> 'U voption) (list : 'T list) : 'U voption =
+        match list with
+        | [] -> ValueNone
+        | head :: tail ->
+            match chooser head with
+            | ValueSome _ as picked -> picked
+            | ValueNone -> tryPick chooser tail
+
+    /// The elements of two lists of the same length, paired by position; lists of different lengths are an error, as for
+    /// the function of FSharp.Core.
+    let zip (first : 'T1 list) (second : 'T2 list) : struct ('T1 * 'T2) list =
+        List.map2 (fun left right -> struct (left, right)) first second
+
+[<RequireQualifiedAccess>]
+module Seq =
+
+    /// The first element, or no value when the sequence is empty.
+    let tryHead (source : 'T seq) : 'T voption =
+        use enumerator = source.GetEnumerator ()
+
+        if enumerator.MoveNext () then
+            ValueSome enumerator.Current
+        else
+            ValueNone
+
+    /// The last element, or no value when the sequence is empty.
+    let tryLast (source : 'T seq) : 'T voption =
+        use enumerator = source.GetEnumerator ()
+
+        if enumerator.MoveNext () then
+            let mutable last = enumerator.Current
+
+            while enumerator.MoveNext () do
+                last <- enumerator.Current
+
+            ValueSome last
+        else
+            ValueNone
+
+    /// The element at the index, or no value when the index is negative or the sequence ends before it.
+    let tryItem (index : int) (source : 'T seq) : 'T voption =
+        if index < 0 then
+            ValueNone
+        else
+            use enumerator = source.GetEnumerator ()
+            let mutable remaining = index
+            let mutable reached = enumerator.MoveNext ()
+
+            while reached && remaining > 0 do
+                remaining <- remaining - 1
+                reached <- enumerator.MoveNext ()
+
+            if reached then ValueSome enumerator.Current else ValueNone
+
+    /// The only element, or no value when the sequence is empty or has more than one element.
+    let tryExactlyOne (source : 'T seq) : 'T voption =
+        use enumerator = source.GetEnumerator ()
+
+        if enumerator.MoveNext () then
+            let only = enumerator.Current
+            if enumerator.MoveNext () then ValueNone else ValueSome only
+        else
+            ValueNone
+
+    /// The first element for which the predicate holds, or no value when it holds for none.
+    let tryFind (predicate : 'T -> bool) (source : 'T seq) : 'T voption =
+        use enumerator = source.GetEnumerator ()
+        let mutable found = ValueNone
+
+        while found.IsNone && enumerator.MoveNext () do
+            let item = enumerator.Current
+
+            if predicate item then
+                found <- ValueSome item
+
+        found
+
+    /// The last element for which the predicate holds, or no value when it holds for none.
+    let tryFindBack (predicate : 'T -> bool) (source : 'T seq) : 'T voption = source |> Seq.toArray |> Array.tryFindBack predicate
+
+    /// The index of the first element for which the predicate holds, or no value when it holds for none.
+    let tryFindIndex (predicate : 'T -> bool) (source : 'T seq) : int voption =
+        use enumerator = source.GetEnumerator ()
+        let mutable index = 0
+        let mutable found = ValueNone
+
+        while found.IsNone && enumerator.MoveNext () do
+            if predicate enumerator.Current then
+                found <- ValueSome index
+
+            index <- index + 1
+
+        found
+
+    /// The index of the last element for which the predicate holds, or no value when it holds for none.
+    let tryFindIndexBack (predicate : 'T -> bool) (source : 'T seq) : int voption =
+        source |> Seq.toArray |> Array.tryFindIndexBack predicate
+
+    /// The first value that the chooser gives for an element, or no value when it gives none.
+    let tryPick (chooser : 'T -> 'U voption) (source : 'T seq) : 'U voption =
+        use enumerator = source.GetEnumerator ()
+        let mutable picked = ValueNone
+
+        while picked.IsNone && enumerator.MoveNext () do
+            picked <- chooser enumerator.Current
+
+        picked
+
+    /// The elements of two sequences, paired by position until the shorter one ends, as for the function of FSharp.Core.
+    let zip (first : 'T1 seq) (second : 'T2 seq) : struct ('T1 * 'T2) seq = Enumerable.Zip (first, second)
diff --git a/tests/Cosmos.Tests/FSharp.Azure.Cosmos.Tests.fsproj b/tests/Cosmos.Tests/FSharp.Azure.Cosmos.Tests.fsproj
index abfdc31e..fd2715c9 100644
--- a/tests/Cosmos.Tests/FSharp.Azure.Cosmos.Tests.fsproj
+++ b/tests/Cosmos.Tests/FSharp.Azure.Cosmos.Tests.fsproj
@@ -21,6 +21,7 @@
     <Compile Include="TestAssembly.fs" />
     <Compile Include="IcedTasksProbeTests.fs" />
     <Compile Include="IterationExtensionsUnitTests.fs" />
+    <Compile Include="ValueCollectionsTests.fs" />
     <Compile Include="CosmosNameTests.fs" />
     <Compile Include="ResponseMessageTests.fs" />
     <Compile Include="DatabaseIdentifierTests.fs" />
diff --git a/tests/Cosmos.Tests/ReadExtensionsTests.fs b/tests/Cosmos.Tests/ReadExtensionsTests.fs
index 6513dcc7..cf6fbcd2 100644
--- a/tests/Cosmos.Tests/ReadExtensionsTests.fs
+++ b/tests/Cosmos.Tests/ReadExtensionsTests.fs
@@ -73,7 +73,7 @@ type ReadExtensionsIntegrationTests () =
             |> Task.WhenAll
 
         let mismatches = [|
-            for struct (id, expected), actual in Array.zip expectations results do
+            for struct (struct (id, expected), actual) in Array.zip expectations results do
                 if expected <> actual then
                     $"{id}: expected {expected}, got {actual}"
         |]
diff --git a/tests/Cosmos.Tests/TestCategories.fs b/tests/Cosmos.Tests/TestCategories.fs
index 2b733741..aedffa65 100644
--- a/tests/Cosmos.Tests/TestCategories.fs
+++ b/tests/Cosmos.Tests/TestCategories.fs
@@ -88,3 +88,11 @@ type ResponseMessageUnitTestCategoryAttribute () =
 type TestInfrastructureUnitTestCategoryAttribute () =
     inherit TestCategoryBaseAttribute ()
     override _.TestCategories = [| "Unit"; "TestInfrastructure" |] :> IList<string>
+
+/// <summary>
+/// Categorizes <see cref="ValueCollectionsTests"/> as both a fast, emulator-free unit test and coverage for the
+/// collection functions of <see cref="T:FSharp.Azure.Cosmos.ValueCollections"/>, which every project compiles.
+/// </summary>
+type ValueCollectionsUnitTestCategoryAttribute () =
+    inherit TestCategoryBaseAttribute ()
+    override _.TestCategories = [| "Unit"; "ValueCollections" |] :> IList<string>
diff --git a/tests/Cosmos.Tests/ValueCollectionsTests.fs b/tests/Cosmos.Tests/ValueCollectionsTests.fs
new file mode 100644
index 00000000..c73ffa91
--- /dev/null
+++ b/tests/Cosmos.Tests/ValueCollectionsTests.fs
@@ -0,0 +1,237 @@
+namespace FSharp.Azure.Cosmos.Tests
+
+open System
+open Microsoft.VisualStudio.TestTools.UnitTesting
+open FSharp.Azure.Cosmos
+
+// The functions of FSharp.Core, which the shadows hide under the short module names
+module CoreSeq = Microsoft.FSharp.Collections.Seq
+module CoreList = Microsoft.FSharp.Collections.List
+module CoreArray = Microsoft.FSharp.Collections.Array
+
+/// Collects the answers of a shadow that differ from those of FSharp.Core, so that a failure names all of them at once.
+type private Differences () =
+
+    let found = ResizeArray<string>()
+
+    /// Records the call when the shadow does not answer what FSharp.Core answers.
+    member _.Expect (call : string, expected : 'T option, actual : 'T voption) =
+        let agrees =
+            match expected, actual with
+            | Some expectedValue, ValueSome actualValue -> expectedValue = actualValue
+            | None, ValueNone -> true
+            | _ -> false
+
+        if not agrees then
+            found.Add $"%s{call}: FSharp.Core gives %A{expected}, the shadow gives %A{actual}"
+
+    /// The recorded differences.
+    member _.Found = found
+
+/// <summary>
+/// Emulator-free coverage of <see cref="T:FSharp.Azure.Cosmos.ValueCollections"/>: every function that shadows one of
+/// <see cref="T:Microsoft.FSharp.Collections.SeqModule"/>, <see cref="T:Microsoft.FSharp.Collections.ListModule"/> or
+/// <see cref="T:Microsoft.FSharp.Collections.ArrayModule"/> answers what that function answers, as a
+/// <see cref="T:Microsoft.FSharp.Core.FSharpValueOption`1"/> or in struct tuples.
+/// </summary>
+[<TestClass; ValueCollectionsUnitTestCategory>]
+type ValueCollectionsTests () =
+
+    // Empty, one element, repeated elements and a longer run
+    static let samples = [| [||]; [| 7 |]; [| 1; 2; 3; 2; 1 |]; [| 4; 4 |]; [| 0..9 |] |]
+
+    static let predicates = [|
+        struct ("never", (fun (_ : int) -> false))
+        struct ("always", (fun (_ : int) -> true))
+        struct ("even", (fun (item : int) -> item % 2 = 0))
+        struct ("two", (fun (item : int) -> item = 2))
+    |]
+
+    // Before the first element, inside the samples and past the end of most of them
+    static let indexes = [| -1; 0; 1; 4; 5 |]
+
+    [<TestMethod>]
+    member _.``Seq shadows answer what the functions of FSharp.Core answer`` () =
+        let differences = Differences ()
+
+        for sample in samples do
+            // A sequence that is not an array, so that nothing can answer from the length of the array
+            let source = sample |> Seq.map id
+
+            differences.Expect ($"tryHead %A{sample}", CoreSeq.tryHead source, Seq.tryHead source)
+            differences.Expect ($"tryLast %A{sample}", CoreSeq.tryLast source, Seq.tryLast source)
+            differences.Expect ($"tryExactlyOne %A{sample}", CoreSeq.tryExactlyOne source, Seq.tryExactlyOne source)
+
+            for index in indexes do
+                differences.Expect ($"tryItem %d{index} %A{sample}", CoreSeq.tryItem index source, Seq.tryItem index source)
+
+            for struct (name, predicate) in predicates do
+                differences.Expect (
+                    $"tryFind %s{name} %A{sample}",
+                    CoreSeq.tryFind predicate source,
+                    Seq.tryFind predicate source
+                )
+
+                differences.Expect (
+                    $"tryFindBack %s{name} %A{sample}",
+                    CoreSeq.tryFindBack predicate source,
+                    Seq.tryFindBack predicate source
+                )
+
+                differences.Expect (
+                    $"tryFindIndex %s{name} %A{sample}",
+                    CoreSeq.tryFindIndex predicate source,
+                    Seq.tryFindIndex predicate source
+                )
+
+                differences.Expect (
+                    $"tryFindIndexBack %s{name} %A{sample}",
+                    CoreSeq.tryFindIndexBack predicate source,
+                    Seq.tryFindIndexBack predicate source
+                )
+
+                differences.Expect (
+                    $"tryPick %s{name} %A{sample}",
+                    source
+                    |> CoreSeq.tryPick (fun item -> if predicate item then Some (item * 10) else None),
+                    source
+                    |> Seq.tryPick (fun item -> if predicate item then ValueSome (item * 10) else ValueNone)
+                )
+
+        Assert.IsEmpty (differences.Found, "Every Seq shadow should answer what the function of FSharp.Core answers.")
+
+    [<TestMethod>]
+    member _.``List shadows answer what the functions of FSharp.Core answer`` () =
+        let differences = Differences ()
+
+        for sample in samples do
+            let source = List.ofArray sample
+
+            differences.Expect ($"tryHead %A{sample}", CoreList.tryHead source, List.tryHead source)
+            differences.Expect ($"tryLast %A{sample}", CoreList.tryLast source, List.tryLast source)
+            differences.Expect ($"tryExactlyOne %A{sample}", CoreList.tryExactlyOne source, List.tryExactlyOne source)
+
+            for index in indexes do
+                differences.Expect ($"tryItem %d{index} %A{sample}", CoreList.tryItem index source, List.tryItem index source)
+
+            for struct (name, predicate) in predicates do
+                differences.Expect (
+                    $"tryFind %s{name} %A{sample}",
+                    CoreList.tryFind predicate source,
+                    List.tryFind predicate source
+                )
+
+                differences.Expect (
+                    $"tryFindBack %s{name} %A{sample}",
+                    CoreList.tryFindBack predicate source,
+                    List.tryFindBack predicate source
+                )
+
+                differences.Expect (
+                    $"tryFindIndex %s{name} %A{sample}",
+                    CoreList.tryFindIndex predicate source,
+                    List.tryFindIndex predicate source
+                )
+
+                differences.Expect (
+                    $"tryFindIndexBack %s{name} %A{sample}",
+                    CoreList.tryFindIndexBack predicate source,
+                    List.tryFindIndexBack predicate source
+                )
+
+                differences.Expect (
+                    $"tryPick %s{name} %A{sample}",
+                    source
+                    |> CoreList.tryPick (fun item -> if predicate item then Some (item * 10) else None),
+                    source
+                    |> List.tryPick (fun item -> if predicate item then ValueSome (item * 10) else ValueNone)
+                )
+
+        Assert.IsEmpty (differences.Found, "Every List shadow should answer what the function of FSharp.Core answers.")
+
+    [<TestMethod>]
+    member _.``Array shadows answer what the functions of FSharp.Core answer`` () =
+        let differences = Differences ()
+
+        for sample in samples do
+            differences.Expect ($"tryHead %A{sample}", CoreArray.tryHead sample, Array.tryHead sample)
+            differences.Expect ($"tryLast %A{sample}", CoreArray.tryLast sample, Array.tryLast sample)
+            differences.Expect ($"tryExactlyOne %A{sample}", CoreArray.tryExactlyOne sample, Array.tryExactlyOne sample)
+
+            for index in indexes do
+                differences.Expect ($"tryItem %d{index} %A{sample}", CoreArray.tryItem index sample, Array.tryItem index sample)
+
+            for struct (name, predicate) in predicates do
+                differences.Expect (
+                    $"tryFind %s{name} %A{sample}",
+                    CoreArray.tryFind predicate sample,
+                    Array.tryFind predicate sample
+                )
+
+                differences.Expect (
+                    $"tryFindBack %s{name} %A{sample}",
+                    CoreArray.tryFindBack predicate sample,
+                    Array.tryFindBack predicate sample
+                )
+
+                differences.Expect (
+                    $"tryFindIndex %s{name} %A{sample}",
+                    CoreArray.tryFindIndex predicate sample,
+                    Array.tryFindIndex predicate sample
+                )
+
+                differences.Expect (
+                    $"tryFindIndexBack %s{name} %A{sample}",
+                    CoreArray.tryFindIndexBack predicate sample,
+                    Array.tryFindIndexBack predicate sample
+                )
+
+                differences.Expect (
+                    $"tryPick %s{name} %A{sample}",
+                    sample
+                    |> CoreArray.tryPick (fun item -> if predicate item then Some (item * 10) else None),
+                    sample
+                    |> Array.tryPick (fun item -> if predicate item then ValueSome (item * 10) else ValueNone)
+                )
+
+        Assert.IsEmpty (differences.Found, "Every Array shadow should answer what the function of FSharp.Core answers.")
+
+    [<TestMethod>]
+    member _.``zip pairs elements into struct tuples and treats lengths as FSharp.Core does`` () =
+        let expected = [| struct (1, "a"); struct (2, "b") |]
+
+        CollectionAssert.AreEqual (
+            expected,
+            Seq.zip [ 1; 2; 3 ] [ "a"; "b" ] |> Seq.toArray,
+            "Seq.zip should pair by position until the shorter sequence ends."
+        )
+
+        CollectionAssert.AreEqual (expected, Array.zip [| 1; 2 |] [| "a"; "b" |], "Array.zip should pair by index.")
+
+        CollectionAssert.AreEqual (expected, List.zip [ 1; 2 ] [ "a"; "b" ] |> List.toArray, "List.zip should pair by position.")
+
+        Assert.ThrowsExactly<ArgumentException>(
+            (fun () -> Array.zip [| 1; 2; 3 |] [| "a"; "b" |] |> ignore),
+            "Array.zip should reject arrays of different lengths, as the function of FSharp.Core does."
+        )
+        |> ignore
+
+        Assert.ThrowsExactly<ArgumentException>(
+            (fun () -> List.zip [ 1; 2; 3 ] [ "a"; "b" ] |> ignore),
+            "List.zip should reject lists of different lengths, as the function of FSharp.Core does."
+        )
+        |> ignore
+
+    [<TestMethod>]
+    member _.``A shadow hides only the function of its name, which stays reachable by its full name`` () =
+        let shadow : int voption = Seq.tryHead [ 1; 2 ]
+        Assert.AreEqual (ValueSome 1, shadow, "Seq.tryHead should be the shadow, which returns a value option.")
+
+        let core : int option = Microsoft.FSharp.Collections.Seq.tryHead [ 1; 2 ]
+        Assert.AreEqual (Some 1, core, "The function of FSharp.Core should stay reachable by its full name.")
+
+        CollectionAssert.AreEqual (
+            [| 2; 3 |],
+            [ 1; 2 ] |> Seq.map ((+) 1) |> Seq.toArray,
+            "A function that only FSharp.Core has, such as Seq.map, should resolve to FSharp.Core."
+        )

From 68f317fd8bce7ef62ee5614cf0e365c1e3169414 Mon Sep 17 00:00:00 2001
From: XperiAndri <xperiandri@outlook.com>
Date: Sat, 10 Oct 2026 13:40:45 +0200
Subject: [PATCH 2/2] docs: describe the shadowed collection functions in the
 agent instructions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/copilot-instructions.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index c4559ec4..15f3518e 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -25,6 +25,8 @@
 │   ├── CosmosResponse.fs – response type wrappers
 │   ├── TaskSeq.fs       – TaskSeq integration
 │   └── UniqueKey.fs     – unique key helpers
+├── src/Shared/          – source files that every F# project under src and tests compiles
+│   └── ValueCollections.fs – `Seq`, `List` and `Array` functions that return `voption` and struct tuples
 ├── tests/Cosmos.Tests/  – MSTest integration test project
 ├── tests/Cosmos.Tests.Infrastructure/ – shared test fixtures, emulator settings and assertion helpers
 ├── build/               – FAKE build scripts
@@ -71,6 +73,7 @@ Agents discover servers from #file:'.mcp.json'; these are only hints on when to
 
 * Prefer `voption` (`ValueSome`/`ValueNone`) over `option`. Fields, members, parameters and values shared between threads included: none of them is a reason to pick `option`. Exception: when an API hands you `'T option` and has no `voption` counterpart, unwrap it with `Option.defaultValue`/`Option.defaultWith` directly – do not insert `ValueOption.ofOption` just to switch modules.
 * The mirror case, an API that *takes* `'T option` (an optional argument `?name = …`, a field typed `'T option`): stay in `ValueOption` through the whole chain and convert once, last – `x |> ValueOption.bind _.Value |> ValueOption.toOption`, never `x |> ValueOption.toOption |> Option.bind _.Value`.
+* The `Seq`, `List` and `Array` functions that return an option in FSharp.Core (`tryHead`, `tryLast`, `tryItem`, `tryExactlyOne`, `tryFind`, `tryFindBack`, `tryFindIndex`, `tryFindIndexBack`, `tryPick`) return a `voption` here, `tryPick` takes a chooser that returns one, and `zip` returns struct tuples: #file:'src/Shared/ValueCollections.fs' shadows them in the namespace `FSharp.Azure.Cosmos` of every F# project under `src` and `tests`, so they are in effect in the code of that namespace and in every file that opens it; a file in another namespace, a child namespace such as `FSharp.Azure.Cosmos.Tests` included, opens `FSharp.Azure.Cosmos` to get them. Match their results with `ValueSome`/`ValueNone`; when another function of this kind is needed, add its shadow to that file instead of converting at the call site. The build project keeps the functions of FSharp.Core.
 * Prefer `struct ('T1 * 'T2)` over reference tuples, and anonymous struct records (`struct {| ... |}`) over tuples for return types of public functions and methods.
 * Never group with `Seq.groupBy` – use `ToLookup` from `System.Linq`. It groups once into an `ILookup<'Key, 'T>` instead of re-grouping on every enumeration and does not allocate a tuple per group. Pass a lambda (`xs.ToLookup (fun x -> keyOf x)`), not a bare function value.
 * When casting sequence items use `Seq.cast<TargetType>` instead of `Seq.map (fun item -> item :> TargetType)`.