Discover shared-only claims and verify actual historical release baselines

Deduplicate immutable alias refs and stop unpublished source claims before selecting another version. Use actual historical tag and release evidence for new-source completeness without changing configured-prefix binding or bump policy.

(cherry picked from commit 3bdda65)

Author: MariusStorhaug

.github/actions/Resolve-PSModuleVersion/README.md

@@ -2,7 +2,7 @@
 
 Resolves the module version once in Plan, before Build. Existing configured bump labels, preview behavior, version prefixes, and prerelease settings remain the decision authority.
 
-For a stable retry, the resolver searches actual version-tag claims for the original immutable consumer source and producing repository/PR or direct-release context. It uses the shared [publication preflight](../Publish-PSModule/README.md) to verify the exact raw Gallery package and any GitHub release/asset evidence before choosing the original version. Numeric equality, release names, mutable targets, and latest-version hints are not ownership proof.
+For a stable retry, the resolver searches both release-tag and shared module/version claims for the original immutable consumer source and producing repository/PR or direct-release context. Refs pointing to the same immutable claim are deduplicated. It uses the shared [publication preflight](../Publish-PSModule/README.md) to verify the exact raw Gallery package and any GitHub release/asset evidence before choosing the original version. Numeric equality, release names, mutable targets, and latest-version hints are not ownership proof.
 
 ## Inputs
 
@@ -22,6 +22,8 @@ The existing `Version`, `Prerelease`, `FullVersion`, `ReleaseType`, and `CreateR
 
 Only one exact source/context claim with matching raw package bytes can select a recovery version. An already-created GitHub release with a missing upload can resume through [Release-PSModule](../Release-PSModule/README.md). The publisher retains the proven Gallery package and verifies the rebuilt/tested artifact again before any write.
 
+An unpublished shared-only claim still stops Plan for original-job retry, even after a later source completes another version. A new source checks baseline completeness using the actual historical tag and release, not a tag reconstructed with the current configured prefix. Recovery and new claims still require exact configured-prefix binding; ambiguous historical baselines stop explicitly.
+
 | Failure | Safe behavior |
 | --- | --- |
 | Gallery-only package has missing, foreign, or legacy proof | Stop version resolution; do not reuse the package or invent a fallback number. |

.github/actions/Resolve-PSModuleVersion/src/Resolve-PSModuleVersion.Helpers.psm1

@@ -761,7 +761,7 @@ function Get-PSModuleGalleryRecoveryVersion {
         Recover a stable version only from exact source/context and raw package proof.
 
         .DESCRIPTION
-        Searches actual version-tag claims, not latest hints or numeric equality.
+        Searches actual release and shared-coordinate claims, not latest hints or numeric equality.
         The canonical preflight validates the original package/release evidence before Build.
         A claimed source without package proof, conflicting context, or multiple versions fails.
 
@@ -806,7 +806,8 @@ function Get-PSModuleGalleryRecoveryVersion {
     )
 
     $number = 0L
-    if ($Context.Repository -notmatch '^[^/\s]+/[^/\s]+$' -or
+    if ($Context.Repository -isnot [string] -or $Context.CommitSha -isnot [string] -or
+        $Context.PullRequest -is [array] -or $Context.Repository -notmatch '^[^/\s]+/[^/\s]+$' -or
         $Context.CommitSha -notmatch '^[0-9a-f]{40}$' -or
         -not [long]::TryParse([string]$Context.PullRequest, [ref]$number) -or $number -lt 0) {
         throw 'Immutable repository/PR/source context is required for Gallery recovery proof.'
@@ -824,25 +825,61 @@ function Get-PSModuleGalleryRecoveryVersion {
     if ($source -cne $Context.CommitSha) {
         throw 'The original consumer source could not be verified before Build.'
     }
-    $owned = [Collections.Generic.List[object]]::new()
+    $owned = [Collections.Generic.Dictionary[string, object]]::new([StringComparer]::Ordinal)
+    $baselineTags = [Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal)
+    $baselineClaims = [Collections.Generic.Dictionary[string, object]]::new([StringComparer]::Ordinal)
     $references = @(& $Reader.GetTagList)
     $prefix = [string]$Configuration.VersionPrefix
+    $coordinatePrefix = 'PSModule-Publication/'
+    $stablePattern = '^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$'
+    $versionPattern = '^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$'
+    $galleryVersion = $null
+    if ($PSGalleryVersion.ToString() -ne '0.0.0') {
+        $galleryVersion = "$($PSGalleryVersion.Major).$($PSGalleryVersion.Minor).$($PSGalleryVersion.Patch)"
+    }
     foreach ($reference in $references) {
         if ($reference.ref -isnot [string] -or -not $reference.ref.StartsWith('refs/tags/') -or
-            $null -eq $reference.object) {
+            $null -eq $reference.object -or $reference.object -is [array] -or
+            $reference.object.sha -isnot [string] -or $reference.object.type -isnot [string] -or
+            $reference.object.sha -notmatch '^[0-9a-f]{40}$' -or
+            $reference.object.type -cnotin @('tag', 'commit')) {
             throw 'The publication tag enumeration returned unverifiable reference metadata.'
         }
         $tag = $reference.ref.Substring('refs/tags/'.Length)
-        if (-not $tag.StartsWith($prefix, [StringComparison]::Ordinal) -or
-            $tag.Substring($prefix.Length) -notmatch '^\d+\.\d+\.\d+$') {
-            continue
+        if ($null -ne $galleryVersion -and -not $tag.StartsWith('PSModule-Publication/', [StringComparison]::Ordinal) -and
+            $tag -cmatch "^\D*$([regex]::Escape($galleryVersion))$") {
+            $null = $baselineTags.Add($tag)
+        }
+        $isCoordinate = $tag.StartsWith($coordinatePrefix, [StringComparison]::Ordinal)
+        if ($isCoordinate) {
+            $coordinateParts = $tag.Substring($coordinatePrefix.Length).Split('/')
+            if ($coordinateParts.Count -ne 2) {
+                throw "The module/version coordinate [$tag] has unverifiable reference metadata."
+            }
+            $tagVersion = $coordinateParts[1]
+            if ($tagVersion -notmatch $versionPattern) {
+                throw "The module/version coordinate [$tag] has unverifiable version metadata."
+            }
+            $moduleCoordinate = Get-PSModulePublicationVersionTag -ModuleName $ModuleName -GalleryVersion $tagVersion
+            if ($tag -cne $moduleCoordinate) { continue }
+            if ($tagVersion.Contains('-')) { continue }
+        } else {
+            if (-not $tag.StartsWith($prefix, [StringComparison]::Ordinal) -or
+                $tag.Substring($prefix.Length) -notmatch $stablePattern) {
+                continue
+            }
+            $tagVersion = $tag.Substring($prefix.Length)
         }
         $evidence = @{ Annotation = $null; Reference = $null }
         $parameters = @{
             Tag             = $tag
             GetTagReference = {
                 param($Tag)
-                $evidence.Reference = & $Reader.GetTagReference $Tag
+                if ($isCoordinate) {
+                    $evidence.Reference = & $Reader.GetVersionReference $ModuleName $tagVersion
+                } else {
+                    $evidence.Reference = & $Reader.GetTagReference $Tag
+                }
                 $evidence.Reference
             }.GetNewClosure()
             GetTagObject    = {
@@ -853,61 +890,101 @@ function Get-PSModuleGalleryRecoveryVersion {
             }.GetNewClosure()
         }
         $tagCommit = Resolve-PSModuleReleaseTagCommit @parameters
+        $claim = $null
+        if ($isCoordinate -or $tagCommit -ceq $Context.CommitSha) {
+            $claim = Get-PSModulePublicationClaim -Message $evidence.Annotation.message
+            if ($null -eq $claim) {
+                throw "Existing source-bound claim [$tag] has no verifiable artifact/release-context proof. Do not invent a fallback version."
+            }
+            if ($claim.CommitSha -cne $tagCommit -or $claim.Repository -ine $Context.Repository -or
+                $claim.ModuleName -cne $ModuleName -or $claim.GalleryVersion -cne $tagVersion -or
+                $claim.ReleaseType -cne 'Release') {
+                throw "The immutable claim [$tag] has conflicting source/module/version proof."
+            }
+            if ($isCoordinate) {
+                $expectedCoordinate = Get-PSModulePublicationVersionTag -ModuleName $claim.ModuleName -GalleryVersion $claim.GalleryVersion
+                if ($tag -cne $expectedCoordinate) {
+                    throw "The shared claim [$tag] does not bind its exact module/version coordinate."
+                }
+            } elseif ($claim.ReleaseTag -cne $tag) {
+                throw "The source-bound tag [$tag] has conflicting release coordinates."
+            }
+            if ($null -ne $galleryVersion -and $claim.GalleryVersion -ceq $galleryVersion) {
+                $null = $baselineTags.Add($claim.ReleaseTag)
+                $baselineClaims[$claim.ReleaseTag] = $claim
+            }
+        }
         if ($tagCommit -cne $Context.CommitSha) {
             continue
         }
-        $claim = Get-PSModulePublicationClaim -Message $evidence.Annotation.message
-        if ($null -eq $claim) {
-            throw "Existing source-bound tag [$tag] has no verifiable artifact/release-context proof. Do not invent a fallback version."
-        }
         if ($claim.Repository -ine $Context.Repository -or $claim.PullRequest -ne $number -or
             $claim.CommitSha -cne $Context.CommitSha -or $claim.ModuleName -cne $ModuleName -or
             $claim.VersionPrefix -cne $prefix -or
-            $claim.ReleaseType -cne 'Release' -or $claim.ReleaseTag -cne $tag -or
-            "$prefix$($claim.GalleryVersion)" -cne $tag) {
+            $claim.ReleaseType -cne 'Release' -or "$prefix$($claim.GalleryVersion)" -cne $claim.ReleaseTag) {
             throw "The source-bound tag [$tag] belongs to a different module or release context."
         }
         $state = Get-PSModulePublicationState -ExpectedClaim $claim -Reader $Reader
-        if ($state.TagSha -cne $evidence.Reference.sha) {
+        $observedSha = $state.TagSha
+        if ($isCoordinate) { $observedSha = $state.VersionTagSha }
+        if ($observedSha -cne $evidence.Reference.sha -or $observedSha -cne $reference.object.sha) {
             throw "Publication claim [$tag] changed while verifying recovery proof. Refusing version resolution."
         }
         if ($null -eq $state.Package) {
             throw ("The original source claim [$tag] has no published raw package proof. " +
                 'Retain its resolved version/artifact and rerun the original job.')
         }
-        $owned.Add($claim)
+        $owned[$observedSha] = $claim
     }
     if ($owned.Count -gt 1) {
         throw 'Multiple published versions claim this exact source and release context. Refusing ambiguous recovery.'
     }
     if ($owned.Count -eq 1) {
-        $version = New-PSSemVer -Version $owned[0].GalleryVersion
+        $original = @($owned.Values)[0]
+        $version = New-PSSemVer -Version $original.GalleryVersion
         $version.Prefix = $prefix
         Write-Verbose "Recovering proven original publication [$($version.ToString())] before Build."
         return $version
     }
-    if ($PSGalleryVersion.ToString() -ne '0.0.0') {
-        $galleryVersion = "$($PSGalleryVersion.Major).$($PSGalleryVersion.Minor).$($PSGalleryVersion.Patch)"
-        $tag = "$prefix$galleryVersion"
-        $release = & $Reader.GetRelease $tag
-        $assets = @($release.assets | Where-Object {
-                $_.name -ceq "$ModuleName-$galleryVersion.zip" -and $_.state -ceq 'uploaded'
-            })
-        if ($null -eq $release -or $release.tag_name -cne $tag -or $release.prerelease -ne $false -or
-            $release.draft -ne $false -or $assets.Count -ne 1) {
-            throw "Gallery-only package [$galleryVersion] has no proven source/artifact recovery context. Do not invent a fallback version."
+    if ($null -ne $galleryVersion) {
+        $completed = [Collections.Generic.List[string]]::new()
+        foreach ($tag in $baselineTags) {
+            $release = & $Reader.GetRelease $tag
+            $assets = @($release.assets | Where-Object {
+                    $_.name -ceq "$ModuleName-$galleryVersion.zip" -and $_.state -ceq 'uploaded'
+                })
+            if ($null -eq $release -or $release.tag_name -cne $tag -or $release.prerelease -isnot [bool] -or
+                $release.prerelease -ne $false -or $release.draft -isnot [bool] -or $release.draft -ne $false -or
+                $assets.Count -ne 1) {
+                continue
+            }
+            if ($baselineClaims.ContainsKey($tag)) {
+                $baselineClaim = $baselineClaims[$tag]
+                $baselineState = Get-PSModulePublicationState -ExpectedClaim $baselineClaim -Reader $Reader
+                if ($null -eq $baselineState.Package) {
+                    throw 'The historical Gallery baseline has no exact published-package proof.'
+                }
+                $baselineSource = $baselineClaim.CommitSha
+            } else {
+                $tagParameters = @{
+                    Tag             = $tag
+                    GetTagReference = $Reader.GetTagReference
+                    GetTagObject    = {
+                        param($Sha)
+                        (& $Reader.GetTagObject $Sha).object
+                    }.GetNewClosure()
+                }
+                $baselineSource = Resolve-PSModuleReleaseTagCommit @tagParameters
+            }
+            if ($baselineSource -ceq $Context.CommitSha) {
+                throw 'The original source already has publication records but recovery proof was not discovered. Do not invent a fallback version.'
+            }
+            $completed.Add($tag)
         }
-        $tagParameters = @{
-            Tag             = $tag
-            GetTagReference = $Reader.GetTagReference
-            GetTagObject    = {
-                param($Sha)
-                (& $Reader.GetTagObject $Sha).object
-            }.GetNewClosure()
+        if ($completed.Count -gt 1) {
+            throw 'Multiple completed tags provide an ambiguous Gallery baseline. Refusing version resolution.'
         }
-        $baselineSource = Resolve-PSModuleReleaseTagCommit @tagParameters
-        if ($baselineSource -ceq $Context.CommitSha) {
-            throw 'The original source already has publication records but recovery proof was not discovered. Do not invent a fallback version.'
+        if ($completed.Count -eq 0) {
+            throw "Gallery-only package [$galleryVersion] has no proven source/artifact recovery context. Do not invent a fallback version."
         }
     }
 }

.github/actions/Resolve-PSModuleVersion/tests/Resolve-PSModuleVersion.Recovery.Tests.ps1

@@ -45,23 +45,23 @@ Describe 'Gallery-only version selection requires original ownership proof' {
         }
         $encoded = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(($claim | ConvertTo-Json -Compress)))
         $record = [pscustomobject]@{
-            Reference   = [pscustomobject]@{
+            Reference        = [pscustomobject]@{
                 ref    = 'refs/tags/v1.2.4'
                 object = [pscustomobject]@{ type = 'tag'; sha = '3333333333333333333333333333333333333333' }
             }
             VersionReference = [pscustomobject]@{
                 ref    = 'refs/tags/PSModule-Publication/testmodule/1.2.4'
                 object = [pscustomobject]@{ type = 'tag'; sha = '3333333333333333333333333333333333333333' }
             }
-            Annotation  = [pscustomobject]@{
+            Annotation       = [pscustomobject]@{
                 sha     = '3333333333333333333333333333333333333333'
                 tag     = 'v1.2.4'
                 object  = [pscustomobject]@{ type = 'commit'; sha = $claim.CommitSha }
                 message = "<!-- PSModule.Publication:v1:$encoded -->"
             }
-            Package     = [pscustomobject]@{ Name = 'TestModule'; Version = '1.2.4' }
-            PackagePath = $packagePath
-            Release     = $null
+            Package          = [pscustomobject]@{ Name = 'TestModule'; Version = '1.2.4' }
+            PackagePath      = $packagePath
+            Release          = $null
         }
         $state = @{
             Record     = $record
@@ -188,19 +188,19 @@ Describe 'Gallery-only version selection requires original ownership proof' {
         $original.Reference = $null
         $original.Package = $null
         $later = [pscustomobject]@{
-            Reference = [pscustomobject]@{
-                ref = 'refs/tags/v1.2.5'
+            Reference        = [pscustomobject]@{
+                ref    = 'refs/tags/v1.2.5'
                 object = [pscustomobject]@{ type = 'tag'; sha = '4444444444444444444444444444444444444444' }
             }
             VersionReference = [pscustomobject]@{
-                ref = 'refs/tags/PSModule-Publication/testmodule/1.2.5'
+                ref    = 'refs/tags/PSModule-Publication/testmodule/1.2.5'
                 object = [pscustomobject]@{ type = 'tag'; sha = '4444444444444444444444444444444444444444' }
             }
-            Annotation = [pscustomobject]@{
+            Annotation       = [pscustomobject]@{
                 sha = '4444444444444444444444444444444444444444'; tag = 'v1.2.5'; message = 'Completed later legacy baseline.'
                 object = [pscustomobject]@{ type = 'commit'; sha = '2222222222222222222222222222222222222222' }
             }
-            Release = [pscustomobject]@{
+            Release          = [pscustomobject]@{
                 tag_name = 'v1.2.5'; prerelease = $false; draft = $false
                 assets = @([pscustomobject]@{ name = 'TestModule-1.2.5.zip'; state = 'uploaded' })
             }
@@ -280,15 +280,15 @@ Describe 'Gallery-only version selection requires original ownership proof' {
             assets = @([pscustomobject]@{ name = 'TestModule-1.2.4.zip'; state = 'uploaded' })
         }
         $other = [pscustomobject]@{
-            Reference = [pscustomobject]@{
-                ref = 'refs/tags/release-1.2.4'
+            Reference  = [pscustomobject]@{
+                ref    = 'refs/tags/release-1.2.4'
                 object = [pscustomobject]@{ type = 'tag'; sha = '4444444444444444444444444444444444444444' }
             }
             Annotation = [pscustomobject]@{
                 sha = '4444444444444444444444444444444444444444'; tag = 'release-1.2.4'; message = 'Another completed legacy baseline.'
                 object = [pscustomobject]@{ type = 'commit'; sha = '2222222222222222222222222222222222222222' }
             }
-            Release = [pscustomobject]@{
+            Release    = [pscustomobject]@{
                 tag_name = 'release-1.2.4'; prerelease = $false; draft = $false
                 assets = @([pscustomobject]@{ name = 'TestModule-1.2.4.zip'; state = 'uploaded' })
             }