FEATURE-ci-v3-integration: bind PR artifact origin to API branch head

The real PR artifact and run APIs report the branch head while GITHUB_SHA identifies the test merge checkout. Supply the trusted event head explicitly to download origin checks, retaining exact selected merge source, archive, run, attempt, repository and digest validation.

Reproduced the actual captured artifact failure twice before repair. Real ZIP replay now validates the branch-head origin and unchanged merge descriptor/archive; 15 release contracts and 10 workflow contracts pass, including negative source/origin/run/attempt/digest controls. Actionlint and Python compilation pass. Native/fuzz/docs/public443 evidence is reused unchanged; fresh actual CI remains root-owned.

Author: etr

.github/workflows/v3-release-acceptance.yml

@@ -26,6 +26,9 @@ name: v3 selected archive acceptance
 permissions:
   contents: read
   actions: read
+env:
+  # Artifact/run APIs identify the PR branch head; checkout tests its merge SHA.
+  WORKFLOW_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
 jobs:
   prepare:
     runs-on: ubuntu-24.04

docs/v3-ci.md

@@ -93,6 +93,12 @@ a download action is insufficient. Artifact creation must belong to the current
 run attempt; rerun all jobs to produce fresh release proof rather than reusing
 artifacts from successful jobs in an earlier attempt.
 
+On PR runs, artifact/run API metadata identifies the PR branch head, while
+`GITHUB_SHA` and the selected checkout identify the test merge commit. Downloads
+bind the API head to the trusted event's PR head. Selected archive preparation
+and platform proof still require the exact selected checkout commit, source
+snapshot and archive bytes; these two source identities are not interchangeable.
+
 The final publisher alone receives `contents: write`. It checks successful
 mandatory dependencies, same-run artifacts, manifest and archive hashes and the
 current tag target before `gh release create --verify-tag`. It runs only inline

scripts/lib/release_ci.py

@@ -85,9 +85,9 @@ def validate_request(root, commit, version):
 
 def verify_download(archive, metadata, run, expected, expected_digest, destination):
     require(str(metadata['id']) == expected['artifact_id'] and metadata['expired'] is False, 'wrong/expired artifact ID')
-    require(str(metadata['workflow_run']['id']) == expected['run_id'] and metadata['workflow_run']['head_sha'] == expected['source_commit'], 'artifact from another workflow source/run')
+    require(str(metadata['workflow_run']['id']) == expected['run_id'] and metadata['workflow_run']['head_sha'] == expected['workflow_head'], 'artifact from another workflow source/run')
     require(str(run['id']) == expected['run_id'] and str(run['run_attempt']) == expected['run_attempt']
-            and run['repository']['full_name'] == expected['repository'] and run['head_sha'] == expected['source_commit'], 'wrong repository/source/run attempt')
+            and run['repository']['full_name'] == expected['repository'] and run['head_sha'] == expected['workflow_head'], 'wrong repository/source/run attempt')
     require(datetime.fromisoformat(metadata['created_at']) >= datetime.fromisoformat(run['run_started_at']), 'artifact belongs to an earlier run attempt')
     from release_artifact import sha256
     digest = 'sha256:' + sha256(archive)

scripts/run-v3-release-ci.py

@@ -129,7 +129,7 @@ def download(args):
     import subprocess
     from release_ci import verify_download
     expected=dict(repository=os.environ['GITHUB_REPOSITORY'],run_id=os.environ['GITHUB_RUN_ID'],
-        run_attempt=os.environ['GITHUB_RUN_ATTEMPT'],source_commit=os.environ['GITHUB_SHA'],artifact_id=args.artifact_id)
+        run_attempt=os.environ['GITHUB_RUN_ATTEMPT'],workflow_head=os.environ['WORKFLOW_HEAD_SHA'],artifact_id=args.artifact_id)
     require(args.artifact_id.isdigit(), 'invalid artifact ID')
     endpoint='repos/'+expected['repository']+'/actions/artifacts/'+args.artifact_id
     metadata=json.loads(subprocess.check_output(['gh','api',endpoint],text=True))

scripts/test-v3-ci-workflows.py

@@ -17,6 +17,11 @@ def workflow(name):
 
 
 class CIWorkflows(unittest.TestCase):
+    def test_artifact_api_head_is_bound_to_trusted_event_head(self):
+        lane = workflow('v3-release-acceptance.yml')
+        self.assertEqual(lane.get('env', {}).get('WORKFLOW_HEAD_SHA'),
+                         '${{ github.event.pull_request.head.sha || github.sha }}')
+
     def test_freebsd_stages_selected_archive_for_vm_transfer(self):
         steps = workflow('v3-release-acceptance.yml')['jobs']['freebsd']['steps']
         run = next(step['run'] for step in steps if 'ci-selected-input' in step.get('run', ''))

specs/tasks/FEATURE-ci-v3-integration.md

@@ -20,7 +20,11 @@ protocol behavior, default-branch setting, tag or release changes.
       and recheck the existing tag before the release side effect.
 - [x] Exercise publication refusal and success through the actual validator,
       with only the final publication side effect mocked.
-- [ ] Root: run the actual GitHub PR pipeline; verify manual dispatch availability.
+- [x] Root: verify manual native campaign dispatch invocation (accepted at
+      08c5b7b5; campaign execution outcomes remain pending).
+- [ ] Root: complete actual GitHub PR pipeline verification. First selected
+      archive attempt failed at API PR-head versus merge-SHA origin binding;
+      causal repair and negative controls passed locally; fresh CI is pending.
 - [ ] CI / v3 PR: obtain fresh full local gate and FreeBSD/Darwin/Windows receipts
       for the selected commit/archive. Missing evidence is not a release pass.
 
@@ -29,7 +33,8 @@ are unchanged and cannot replace fresh evidence.
 
 Local verification: native TLS-off/on suites (239/270 tests, two documented
 nonlocal backend skips in each), all eleven sanitizer fuzz targets, genuine
-Doxygen/Graphviz, GCC QUIC replay and 100 focused CI/release/fuzz contracts passed.
+Doxygen/Graphviz, GCC QUIC replay and 100 initial CI/release/fuzz contracts passed.
+The subsequent artifact-origin repair adds three focused contracts (103 total).
 The fresh Linux installed attempt passed TLS-off but failed TLS-on public TLS at
 unprivileged TCP443 binding. Its unsuccessful receipt remains unchanged. A fresh
 focused public TLS run using the existing isolated network path passed all four

test/integ/release_ci_test.py

@@ -151,7 +151,7 @@ def test_immutable_download_checks_source_run_attempt_digest_and_zip_members(sel
         ci=self.ci()
         archive=self.directory/'artifact.zip'
         with zipfile.ZipFile(archive,'w') as stream: stream.writestr('selected.json','selected bytes')
-        expected=dict(repository='etr/libhttpserver',run_id='12',run_attempt='1',source_commit='d'*40,artifact_id='23')
+        expected=dict(repository='etr/libhttpserver',run_id='12',run_attempt='1',workflow_head='d'*40,artifact_id='23')
         metadata=dict(id=23,expired=False,created_at='2026-10-15T03:01:00Z',workflow_run={'id':12,'head_sha':'d'*40},digest='sha256:'+hashlib.sha256(archive.read_bytes()).hexdigest())
         run=dict(id=12,run_attempt=1,run_started_at='2026-10-15T03:00:00Z',repository={'full_name':'etr/libhttpserver'},head_sha='d'*40)
         ci.verify_download(archive,metadata,run,expected,metadata['digest'],self.directory/'download')
@@ -168,6 +168,59 @@ def test_immutable_download_checks_source_run_attempt_digest_and_zip_members(sel
             with self.subTest(name=name),self.assertRaises(ValueError):
                 ci.verify_download(bad,dict(metadata,digest=digest),run,expected,digest,self.directory/('badzip-%d'%index))
 
+    def test_pr_download_binds_api_branch_head_and_retains_merge_source_descriptor(self):
+        import hashlib
+        import zipfile
+        ci=self.ci()
+        head='08c5b7b5eb5e992f5a12d88136064010fc435f9d'
+        merge='b5f8d51fe8b597fb3c720aa5459c04b9147c615b'
+        archive=self.directory/'pr-artifact.zip'
+        with zipfile.ZipFile(archive,'w') as stream:
+            stream.writestr('selected.json',json.dumps({'commit':merge,'source':{'head':merge}}))
+        digest='sha256:'+hashlib.sha256(archive.read_bytes()).hexdigest()
+        expected=dict(repository='etr/libhttpserver',run_id='38848731938',run_attempt='1',workflow_head=head,artifact_id='12024142302')
+        metadata=dict(id=12024142302,expired=False,created_at='2026-10-16T04:05:15Z',
+            workflow_run=dict(id=38848731938,head_sha=head),digest=digest)
+        run=dict(id=38848731938,run_attempt=1,head_sha=head,event='pull_request',
+            repository={'full_name':'etr/libhttpserver'},run_started_at='2026-10-16T04:04:45Z')
+        destination=self.directory/'pr-download'
+        ci.verify_download(archive,metadata,run,expected,digest,destination)
+        self.assertEqual(json.loads((destination/'selected.json').read_text())['commit'],merge)
+        for index, altered in enumerate((dict(expected,workflow_head=merge),dict(expected,workflow_head='a'*40),
+                dict(expected,run_id='38848731939'),dict(expected,run_attempt='2'),dict(expected,repository='other/repo'))):
+            with self.subTest(expected=altered),self.assertRaises(ValueError):
+                ci.verify_download(archive,metadata,run,altered,digest,self.directory/('wrong-pr-'+str(index)))
+        for field,value in (('id',12024142303),('workflow_run',dict(id=38848731939,head_sha=head)),
+                            ('workflow_run',dict(id=38848731938,head_sha=merge)),('digest','sha256:'+'a'*64)):
+            with self.subTest(field=field,value=value),self.assertRaises(ValueError):
+                ci.verify_download(archive,dict(metadata,**{field:value}),run,expected,digest,self.directory/'wrong-origin')
+
+    def test_download_entrypoint_uses_trusted_api_head_instead_of_pr_merge_sha(self):
+        import argparse
+        import hashlib
+        import io
+        import os
+        import zipfile
+        from unittest.mock import patch
+        spec=importlib.util.spec_from_file_location('release_ci_entrypoint',ROOT/'scripts/run-v3-release-ci.py')
+        entrypoint=importlib.util.module_from_spec(spec); spec.loader.exec_module(entrypoint)
+        head='08c5b7b5eb5e992f5a12d88136064010fc435f9d'; merge='b5f8d51fe8b597fb3c720aa5459c04b9147c615b'
+        stream=io.BytesIO()
+        with zipfile.ZipFile(stream,'w') as archive: archive.writestr('selected.json',json.dumps({'commit':merge}))
+        contents=stream.getvalue(); digest='sha256:'+hashlib.sha256(contents).hexdigest()
+        metadata=dict(id=12024142302,expired=False,created_at='2026-10-16T04:05:15Z',
+            workflow_run=dict(id=38848731938,head_sha=head),digest=digest)
+        run=dict(id=38848731938,run_attempt=1,head_sha=head,repository={'full_name':'etr/libhttpserver'},run_started_at='2026-10-16T04:04:45Z')
+        def transport(argv,stdout,check):
+            self.assertEqual(argv,['gh','api','repos/etr/libhttpserver/actions/artifacts/12024142302/zip'])
+            stdout.write(contents)
+        env=dict(GITHUB_REPOSITORY='etr/libhttpserver',GITHUB_RUN_ID='38848731938',GITHUB_RUN_ATTEMPT='1',
+                 GITHUB_SHA=merge,WORKFLOW_HEAD_SHA=head)
+        args=argparse.Namespace(artifact_id='12024142302',digest=digest,output=self.directory/'cli-download')
+        with patch.dict(os.environ,env),patch('subprocess.check_output',side_effect=[json.dumps(metadata),json.dumps(run)]),patch('subprocess.run',side_effect=transport):
+            entrypoint.download(args)
+        self.assertEqual(json.loads((args.output/'selected.json').read_text())['commit'],merge)
+
     def test_exact_commit_request_rejects_modified_and_untracked_source_inputs(self):
         import subprocess
         ci=self.ci(); root=self.directory/'checkout'; (root/'scripts').mkdir(parents=True)