Document shared package ownership and tested version binding

Author: MariusStorhaug

.github/actions/Publish-PSModule/README.md

@@ -2,7 +2,7 @@
 
 Publishes a pre-versioned, tested PowerShell module artifact to the PowerShell Gallery after source-bound ownership preflight. GitHub Release creation is handled by the separate [Release-PSModule](../Release-PSModule/README.md) action.
 
-The publisher verifies the original source, exact resolved tag/version, producing repository/PR or direct-release context, and tested bytes before an external versioned-artifact mutation. An absent version is reserved with a create-only annotated tag containing the file-tree and ZIP SHA-256 proof. Existing tags are never updated or deleted.
+The publisher verifies the original source, exact resolved tag/version, producing repository/PR or direct-release context, and tested bytes before an external versioned-artifact mutation. An absent Gallery module/version is reserved at `PSModule-Publication/<lowercase-module>/<lowercase-version>`, independently of the configured release-tag prefix. The shared coordinate and release tag reference the same immutable annotated source/context/file-tree/ZIP claim. Existing tags are never updated or deleted; the package ownership coordinate is retained for immutable Gallery proof.
 
 An existing Gallery package is retained only when its raw nupkg payload matches that proof and the tested artifact. Package code is never imported to establish ownership. Unknown legacy proof, foreign tags/releases/assets, changed claims, authentication errors, and API failures stop publication explicitly.
 
@@ -15,6 +15,7 @@ An existing Gallery package is retained only when its raw nupkg payload matches
 | `ArtifactName` | Name of the module artifact to download. | No | `module` |
 | `PSGALLERY_API_KEY` | PowerShell Gallery API key. | Yes | N/A |
 | `ReleaseTag` | Exact tag already resolved as `Publish.Module.Resolution.FullVersion`. | Yes | N/A |
+| `VersionPrefix` | Existing resolver prefix used to bind `ReleaseTag` to the tested module version. | No | `v` |
 | `CommitSha` | Immutable commit that produced the tested artifact. | No | Original workflow `GITHUB_SHA` |
 | `PullRequest` | Normalized producing-PR context; empty for a direct stable release. | No | Empty |
 | `WhatIf` | Logs publishing operations without publishing the module. | No | `false` |
@@ -35,10 +36,13 @@ This action does not provide outputs.
     ArtifactName: module
     PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
     ReleaseTag: ${{ fromJson(inputs.Settings).Publish.Module.Resolution.FullVersion }}
+    VersionPrefix: ${{ fromJson(inputs.Settings).Publish.Module.VersionPrefix }}
     CommitSha: ${{ fromJson(inputs.Settings).Context.CommitSha }}
     PullRequest: ${{ toJson(fromJson(inputs.Settings).Context.PullRequest) }}
 ```
 
 Provide `GH_TOKEN` with contents-write access scoped to the consumer repository. The reusable workflow supplies its existing GitHub App token and resolved context internally.
 
+NuGet-reserved container metadata paths are rejected in the tested candidate before a claim or upload, using the same path classification as raw package verification. A published package without its shared module/version coordinate is unproven; the publisher does not fabricate that ownership record on retry.
+
 Use [Release-PSModule](../Release-PSModule/README.md) in a separate step to create the GitHub release from the same source and tested artifact. A retry must retain the original coordinates and bytes; unproven legacy publication requires reviewed forward-only recovery, not numeric guessing, retagging, or metadata changes.

.github/actions/Release-PSModule/README.md

@@ -10,6 +10,7 @@ Creates or resumes a GitHub release for a pre-versioned, tested PowerShell modul
 | `ModulePath` | Path containing the built `<Name>/` module directory. | No | `.PSModule/module` |
 | `ArtifactName` | Name of the module artifact to download. | No | `module` |
 | `ReleaseTag` | Full GitHub release tag resolved by `Resolve-PSModuleVersion`. | Yes | N/A |
+| `VersionPrefix` | Existing configured resolver prefix; verifies tag/artifact version binding. | No | `v` |
 | `CommitSha` | Original immutable build source for stable and prerelease tags. | No | Original workflow `GITHUB_SHA` |
 | `PullRequest` | Normalized producing-PR context; empty for a direct stable release. | No | Empty |
 | `WhatIf` | Logs release operations without creating or uploading anything. | No | `false` |
@@ -38,12 +39,13 @@ Pass the Plan job's resolved `FullVersion` as `ReleaseTag` so the configured tag
     ModulePath: .PSModule/module
     ArtifactName: module
     ReleaseTag: ${{ fromJson(inputs.Settings).Publish.Module.Resolution.FullVersion }}
+    VersionPrefix: ${{ fromJson(inputs.Settings).Publish.Module.VersionPrefix }}
     CommitSha: ${{ fromJson(inputs.Settings).Context.CommitSha }}
     PullRequest: ${{ toJson(fromJson(inputs.Settings).Context.PullRequest) }}
 ```
 
 The action supports normalized pull-request context and direct stable releases. Provide repository-scoped contents-write `GH_TOKEN` access and the original tested artifact/source. Tags resolve to actual commits, including annotated tags; mutable branch names and release target hints are not ownership proof.
 
-Release creation and upload recheck the tag, provenance, and artifact identity. A missing upload can resume. An existing asset is retained only when its published SHA-256 matches the exact local ZIP; differing, ambiguous, or unverifiable bytes stop the action. Uploads never use `--clobber`, and tags are never retargeted.
+Release creation and upload recheck the release tag, shared module/version coordinate, provenance, and artifact identity. Both refs must bind the same immutable claim, regardless of tag prefix. A missing upload can resume. An existing asset is retained only when its published SHA-256 matches the exact local ZIP; differing, ambiguous, or unverifiable bytes stop the action. Uploads never use `--clobber`, and tags are never retargeted.
 
 Complete authored or generated prerelease notes precede a final repository/producing-PR/source footer. A matching tag/source does not authorize another PR's release. Legacy records without proof require reviewed forward-only recovery; the action does not fabricate provenance or alter consumer metadata.

docs/content/guides/versioning-and-releases.md

@@ -77,12 +77,16 @@ Release names and notes can be generated from the pull request — see
 
 Before taking a Gallery version, the publisher verifies the immutable consumer source, the Plan job's exact
 resolved version/tag, the producing repository/PR or direct-release context, and the tested module bytes.
-An absent version tag is reserved with a create-only annotated claim containing the tested file-tree and
-release-ZIP SHA-256 digests. Existing tags are not updated or deleted.
+The Gallery module/version is reserved at a prefix-independent `PSModule-Publication/<module>/<version>`
+coordinate, and the configured release tag references that same immutable annotated claim. It records the
+source/context, tested file-tree and release-ZIP SHA-256 digests. The resolver's existing prefix must bind
+the tag to the tested artifact version. Existing tags are not updated or deleted.
 
 Standalone tags, annotated tags, releases, provenance footers, module assets, and exact Gallery packages must
 agree with that claim. Raw nupkg files are read without importing package code. Verified absence is different
 from an authentication/API failure or unknown ownership proof; errors and unavailable proof stop publication.
+NuGet-reserved container paths are rejected in the tested candidate before claiming or uploading, rather
+than being discarded only when verifying a published package.
 
 The publisher rechecks the claim and tested files immediately before Gallery upload. GitHub release creation
 and upload repeat the ownership checks. Missing uploads may resume, identical published ZIP bytes are retained,