Respond to PEP Delegate's feedback

* Remove the "action" keys in request bodies, and substitute for explicit end-points.  This feels much more
  REST-ish.  This is for both the publishing and file upload sessions.
* Add an `authentication` cross-reference anchor.
* Add a Recommendations for Client Implementers section for how clients like twine, uv, and GitHub
  actions *might* utilize the PEP 694 API.
* Update the Change Log accordingly.

Author: warsaw

peps/pep-0694.rst

@@ -253,6 +253,8 @@ the url structure of a domain. For example, the root endpoint could be
 The choice of the root endpoint is left up to the index operator.
 
 
+.. _authentication:
+
 Authentication for Upload 2.0 API
 ----------------------------------
 
@@ -421,6 +423,8 @@ The successful response includes the following content:
         "stage": "...",
         "upload": "...",
         "session": "...",
+        "publish": "...",
+        "extend": "...",
       },
       "mechanisms": ["http-post-bytes"],
       "session-token": "<token-string>",
@@ -481,7 +485,9 @@ Multiple Session Creation Requests
 If a second attempt to create a session is received for the same name-version pair while a session for that
 pair is in the ``pending``, ``processing``, or ``complete`` state, then a new session is *not* created.
 Instead, the server **MUST** respond with a ``409 Conflict`` and **MUST** include a ``Location`` header that
-points to the :ref:`session status URL <publishing-session-status>`.
+points to the :ref:`session status URL <publishing-session-status>`.  Subsequent session creation requests
+**MUST** be performed with the same credentials as the in-progress session, otherwise a ``403 Forbidden`` is
+returned.
 
 For sessions in the ``error`` or ``canceled`` state, a new session is created with same ``201 Created``
 response and payload, except that the :ref:`publishing session status URL <publishing-session-status>`,
@@ -495,12 +501,16 @@ Publishing Session Links
 For the ``links`` key in the success JSON, the following sub-keys are valid:
 
 ``session``
-    The endpoint where actions for this session can be performed,
-    including :ref:`publishing this session <publishing-session-completion>`,
-    :ref:`canceling and discarding the session <publishing-session-cancellation>`,
-    :ref:`querying the current session status <publishing-session-status>`,
-    and :ref:`requesting an extension of the session lifetime <publishing-session-extension>`
-    (*if* the server supports it).
+    The endpoint where the session resource can be accessed for
+    :ref:`querying the current session status <publishing-session-status>` (via ``GET``)
+    and :ref:`canceling and discarding the session <publishing-session-cancellation>` (via ``DELETE``).
+
+``publish``
+    The endpoint for :ref:`publishing this session <publishing-session-completion>` (via ``POST``).
+
+``extend``
+    The endpoint for :ref:`requesting an extension of the session lifetime <publishing-session-extension>`
+    (via ``POST``).  If the server does not support session extensions, this key **MUST** be omitted.
 
 ``upload``
     The endpoint session clients will use to initiate a :ref:`file upload session <file-upload-session>`
@@ -550,7 +560,7 @@ Complete a Publishing Session
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To complete a session and publish the files that have been included in it, a client issues a
-``POST`` request to the ``session`` :ref:`link <publishing-session-links>`
+``POST`` request to the ``publish`` :ref:`link <publishing-session-links>`
 given in the :ref:`session creation response body <publishing-session-response>`.
 
 The request looks like:
@@ -560,8 +570,7 @@ The request looks like:
     {
       "meta": {
         "api-version": "2.0"
-      },
-      "action": "publish",
+      }
     }
 
 
@@ -614,7 +623,8 @@ Publishing Session Extension
 
 Servers **MAY** allow clients to extend sessions, but the overall lifetime and number of extensions
 allowed is left to the server.  To extend a session, a client issues a ``POST`` request to the
-:ref:`links.session <publishing-session-links>` URL (same as above, also the ``Location`` header).
+:ref:`links.extend <publishing-session-links>` URL.  If the server does not support session extensions,
+the ``links.extend`` key will not be present in the response.
 
 The request looks like:
 
@@ -624,7 +634,6 @@ The request looks like:
       "meta": {
         "api-version": "2.0"
       },
-      "action": "extend",
       "extend-for": 3600
     }
 
@@ -756,7 +765,9 @@ The successful response includes the following:
         "api-version": "2.0"
       },
       "links": {
-        "file-upload-session": "..."
+        "file-upload-session": "...",
+        "complete": "...",
+        "extend": "..."
       },
       "status": "pending",
       "expires-at": "2025-08-01T13:00:00Z",
@@ -801,30 +812,35 @@ File Upload Session Links
 For the ``links`` key in the response payload, the following sub-keys are valid:
 
 ``file-upload-session``
-    The endpoint where actions for this file-upload-session can be performed.  including :ref:`completing a
-    file upload session <file-upload-session-completion>`, :ref:`canceling and discarding the file upload
-    session <file-upload-session-cancellation>`, :ref:`querying the current file upload session status
-    <file-upload-session-status>`, and :ref:`requesting an extension of the file upload session lifetime
-    <file-upload-session-extension>` (*if* the server supports it).
+    The endpoint where the file upload session resource can be accessed for
+    :ref:`querying the current file upload session status <file-upload-session-status>` (via ``GET``)
+    and :ref:`canceling and discarding the file upload session <file-upload-session-cancellation>` (via ``DELETE``).
+
+``complete``
+    The endpoint for :ref:`completing a file upload session <file-upload-session-completion>` (via ``POST``).
+
+``extend``
+    The endpoint for :ref:`requesting an extension of the file upload session lifetime
+    <file-upload-session-extension>` (via ``POST``).  If the server does not support file upload session
+    extensions, this key **MUST** be omitted.
 
 .. _file-upload-session-completion:
 
 Complete a File Upload Session
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To complete a file upload session, which indicates that the file upload mechanism has been executed
-and did not produce an error, a client issues a ``POST`` to the ``file-upload-session`` link in the
-file upload session creation response body.
+and did not produce an error, a client issues a ``POST`` to the ``complete`` :ref:`link
+<file-upload-session-links>` in the file upload session creation response body.
 
-The requests looks like:
+The request looks like:
 
 .. code-block:: json
 
     {
       "meta": {
         "api-version": "2.0"
-      },
-      "action": "complete",
+      }
     }
 
 If the server is able to immediately complete the file upload session, it may do so and return a ``201
@@ -887,8 +903,9 @@ File Upload Session Extension
 
 Servers **MAY** allow clients to extend file upload sessions, but the overall lifetime and number of
 extensions allowed is left to the server.  To extend a file upload session, a client issues a ``POST`` request
-to the ``links.file-upload-session`` URL from the :ref:`file upload session creation response
-<file-upload-session-response>`.
+to the ``extend`` :ref:`link <file-upload-session-links>` from the :ref:`file upload session creation response
+<file-upload-session-response>`.  If the server does not support file upload session extensions,
+the ``links.extend`` key will not be present in the response.
 
 The request looks like:
 
@@ -898,7 +915,6 @@ The request looks like:
       "meta": {
         "api-version": "2.0"
       },
-      "action": "extend",
       "extend-for": 3600
     }
 
@@ -1035,6 +1051,200 @@ If a server intends to precisely match the behavior of another server's implemen
 with that implementation's file upload mechanism name.
 
 
+.. _client-recommendations:
+
+Recommendations for Client Implementers
+=======================================
+
+This section is non-normative and provides guidance for client tool authors
+implementing the Upload 2.0 protocol.  These recommendations are suggestions
+based on the expected usage patterns of the protocol; client authors are free
+to implement alternative approaches that best suit their users' needs.
+
+General Workflow
+----------------
+
+A typical upload workflow using the Upload 2.0 protocol follows these steps:
+
+1. Create a :ref:`publishing session <publishing-session-create>` for the project name and version.
+2. For each artifact (sdist, wheels), :ref:`create a file upload session <file-upload-session>`,
+   execute the negotiated upload mechanism, and :ref:`complete the file upload session
+   <file-upload-session-completion>`.
+3. Optionally, if the index supports :ref:`stage previews <staged-preview>`, use the ``links.stage``
+   URL to test the release before publishing.
+4. :ref:`Publish the session <publishing-session-completion>` to make the release public,
+   or :ref:`cancel it <publishing-session-cancellation>` if issues are discovered.
+
+Clients **SHOULD** handle failures gracefully at each step.  If an error occurs during file upload,
+the client should :ref:`cancel the file upload session <file-upload-session-cancellation>`.  If an
+unrecoverable error occurs at any point, the client should :ref:`cancel the publishing session
+<publishing-session-cancellation>` to clean up server-side resources.
+
+Parallel Uploads
+~~~~~~~~~~~~~~~~
+
+Clients **MAY** upload multiple files in parallel by creating and executing multiple file upload
+sessions concurrently within the same publishing session.  This can significantly improve upload
+times for releases with many wheel variants.  However, clients should be prepared for servers that
+do not support parallel uploads and may return ``409 Conflict`` if parallel uploads are attempted.
+
+Session Management
+~~~~~~~~~~~~~~~~~~
+
+Clients should monitor the ``expires-at`` timestamp in session responses.  For long-running uploads
+(e.g., large files on slow connections), clients may need to :ref:`request session extensions
+<publishing-session-extension>` if the ``links.extend`` endpoint is available.  If the server does
+not support extensions (indicated by the absence of ``links.extend``), clients should warn users
+when uploads may exceed the session lifetime.
+
+Suggested Command-Line Interfaces
+---------------------------------
+
+The following examples illustrate how existing tools might expose the Upload 2.0 protocol to users.
+These are suggestions only; actual implementations may vary.
+
+twine
+~~~~~
+
+`twine <https://twine.readthedocs.io/>`__ currently provides a simple ``twine upload dist/*``
+command.  The Upload 2.0 protocol could be exposed through additional options:
+
+``twine upload dist/*``
+    Maintains backward compatibility.  Uses the Upload 2.0 protocol if available, falling back to
+    the legacy protocol if not.  Creates a session, uploads all files, and publishes immediately.
+
+``twine upload --stage dist/*``
+    Uses the Upload 2.0 protocol to create a session and upload files, but does not publish.
+    This is useful even when the index does not support stage preview URLs, as it still provides
+    the atomic release semantics of Upload 2.0.  If the index supports stage previews, prints the
+    ``links.stage`` URL for testing.  Prints a session identifier that can be used with subsequent
+    commands.  This session identifier is local to the client and is mapped internally to the
+    in-progress server session.
+
+``twine publish <session-id>``
+    Publishes a previously staged session.
+
+``twine cancel <session-id>``
+    Cancels a staged session and discards all uploaded files.
+
+``twine status <session-id>``
+    Queries and displays the current status of a session.
+
+uv
+~~
+
+`uv <https://docs.astral.sh/uv/>`__ could provide similar functionality with additional integration:
+
+``uv publish dist/*``
+    Creates a session, uploads all files, and publishes.  May leverage parallel uploads for
+    faster publishing of multiple wheels.
+
+``uv publish --stage dist/*``
+    Uploads without publishing.  Like twine, this is valuable even without stage preview support.
+
+``uv publish --test-install dist/*``
+    If the index supports stage previews, uploads files, installs the package from the stage URL
+    into a temporary virtual environment, optionally runs a smoke test command, and only publishes
+    if successful.  This provides an integrated "upload, test, publish" workflow.
+
+GitHub Actions
+~~~~~~~~~~~~~~
+
+The `pypa/gh-action-pypi-publish <https://github.com/pypa/gh-action-pypi-publish>`__ action could
+leverage staged releases to enable powerful CI/CD workflows.  A multi-job workflow might look like:
+
+.. code-block:: yaml
+
+    jobs:
+      upload:
+        runs-on: ubuntu-latest
+        outputs:
+          stage-url: ${{ steps.upload.outputs.stage-url }}
+          session-id: ${{ steps.upload.outputs.session-id }}
+        steps:
+          - uses: actions/download-artifact@v4
+            with:
+              name: dist
+              path: dist/
+          - id: upload
+            uses: pypa/gh-action-pypi-publish@v2
+            with:
+              stage-only: true  # Upload but don't publish
+
+      test:
+        needs: upload
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/setup-python@v5
+          - name: Test staged release
+            run: |
+              pip install --extra-index-url "${{ needs.upload.outputs.stage-url }}" my-package
+              python -c "import my_package; my_package.smoke_test()"
+
+      publish:
+        needs: [upload, test]
+        runs-on: ubuntu-latest
+        steps:
+          - uses: pypa/gh-action-pypi-publish@v2
+            with:
+              publish-session: ${{ needs.upload.outputs.session-id }}
+
+This pattern allows the actual PyPI artifacts to be tested in a realistic installation scenario
+before being published.  If the test job fails, the workflow can include a cleanup job to cancel
+the session:
+
+.. code-block:: yaml
+
+      cancel-on-failure:
+        needs: [upload, test]
+        if: failure()
+        runs-on: ubuntu-latest
+        steps:
+          - uses: pypa/gh-action-pypi-publish@v2
+            with:
+              cancel-session: ${{ needs.upload.outputs.session-id }}
+
+Even when the index does not support stage preview URLs, the staged upload pattern is still
+valuable as it ensures atomic releases: either all artifacts are published together, or none are.
+
+Error Handling
+--------------
+
+Clients should implement robust error handling for the multi-step upload process:
+
+**File upload failures**: If a file upload fails (network error, validation error, etc.), the
+client should :ref:`cancel that file upload session <file-upload-session-cancellation>` before
+retrying.  The client may then create a new file upload session for the same filename.
+
+**Partial upload recovery**: If some files have been successfully uploaded but others fail, the
+client has options:
+
+- Cancel the entire publishing session and start over.
+- Cancel only the failed file upload sessions and retry those files.
+- If using ``--stage`` mode, leave the session open for manual intervention.
+
+**Session expiration**: If a session expires during upload, the client must create a new publishing
+session and re-upload all files.  Clients should monitor ``expires-at`` and warn users proactively.
+
+**Publishing failures**: If the publish request fails, the session remains in its current state.
+The client can query the session status to determine the cause and retry the publish operation.
+
+**Graceful cancellation**: When a user interrupts an upload (e.g., Ctrl+C), clients should attempt
+to cancel the publishing session to avoid leaving orphaned sessions on the server.
+
+Legacy API Fallback
+-------------------
+
+During the transition period, clients **SHOULD** support both the Upload 2.0 and legacy protocols.
+A suggested approach:
+
+1. Attempt to use Upload 2.0 by checking for the 2.0 endpoint or using content negotiation.
+2. If the server does not support Upload 2.0 (e.g., returns ``404`` or ``406``), fall back to the
+   legacy protocol.
+3. Provide a command-line option to force a specific protocol version if needed for debugging or
+   compatibility.
+
+
 FAQ
 ===
 
@@ -1105,7 +1315,16 @@ as experience is gained operating Upload 2.0.
 Change History
 ==============
 
-* `06-Dec-2025 <TBD>`__
+* `26-Jan-2026 <TBD>`__
+
+  * Session actions now use dedicated endpoint links instead of an ``action`` key in request bodies.
+    Publishing sessions add ``links.publish`` and ``links.extend``; file upload sessions add
+    ``links.complete`` and ``links.extend``.  The ``links.session`` and ``links.file-upload-session``
+    endpoints are now used only for ``GET`` (status) and ``DELETE`` (cancel) operations.
+  * Add non-normative :ref:`Recommendations for Client Implementers <client-recommendations>` section
+    with suggested UX patterns for tools like twine, uv, and GitHub Actions.
+
+* `06-Dec-2025 <https://discuss.python.org/t/pep-694-pypi-upload-api-2-0-round-2/101483/35>`__
 
   * Error responses conform to the :rfc:`9457` format.