CI: Actually use the cache dependencies

Previously the GHAs would store the cache after building the
dependencies but never restore them. Did a thorough investigation
of the issue and added proper comments about how it works and why.

.github/workflows/haskell.yml

@@ -59,16 +59,22 @@ jobs:
     - name: Cabal update
       run: cabal update
 
+<<<<<<< diff from left file
     - name: Configure build
       shell: bash
       run: |
         cp ".github/workflows/cabal.project.local.ci.$(uname -s)" cabal.project.local
         echo "# cabal.project.local"
         cat cabal.project.local
 
+========
+    # A dry run `build all` operation does *NOT* downlaod anything, it just looks at the package
+    # indices to generate an install plan.
+>>>>>>> diff from right file
     - name: Build dry run
       run: cabal build all --enable-tests --dry-run --minimize-conflict-set
 
+    # From the install plan we generate a dependency list.
     - name: Record dependencies
       id: record-deps
       run: |
@@ -77,17 +83,37 @@ jobs:
         ${{ (runner.os == 'Windows' && '$env:PATH=("C:\msys64\mingw64\bin;{0}" -f $env:PATH)') || '' }}
         cat dist-newstyle/cache/plan.json | jq -r '."install-plan"[].id' | sort | uniq > dependencies.txt
 
+    # From the dependency list we restore the cached dependencies.
+    # We use the hash of `dependencies.txt` as part of the cache key because that will be stable
+    # until the `index-state` values in the `cabal.project` file changes.
+    - name: Restore cached dependencies
+      uses: actions/cache/restore@v4
+      id: cache
+      with:
+        path: |
+          ${{ steps.setup-haskell.outputs.cabal-store }}
+          dist-newstyle
+        key: cache-${{ env.CABAL_CACHE_VERSION }}-${{ runner.os }}-${{ matrix.ghc }}-${{ hashFiles('dependencies.txt') }}
+        restore-keys: |
+          ${{ runner.os }}-ghc-${{ env.GHC_VERSION }}-cabal-${{ env.CABAL_VERSION }}-
+          cache-${{ env.CABAL_CACHE_VERSION }}-${{ runner.os }}-${{ matrix.ghc }}-${{ hashFiles('dependencies.txt') }}
+
+    # Now we install the dependencies. If the cache was found and restored in the previous step,
+    # this should be a no-op, but if the cache key was not found we need to build stuff so we can
+    # cache it for the next step.
     - name: Install dependencies
       run: cabal build all --enable-tests --only-dependencies -j --ghc-option=-j4
 
+    # Always store the cabal cache.
     - name: Cache Cabal store
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       with:
         path: |
           ${{ steps.setup-haskell.outputs.cabal-store }}
           dist-newstyle
         key: cache-${{ env.CABAL_CACHE_VERSION }}-${{ runner.os }}-${{ matrix.ghc }}-${{ hashFiles('dependencies.txt') }}
 
+    # Now we build.
     - name: Build [testing]
       run: cabal build all --enable-tests -j --ghc-option=-j4