ci: handle new-branch OpenAPI comparisons and align delivery

Compare a branch-creation push against the selected head's parent
instead of GitHub's zero before SHA. Preserve existing event refs and
prove selection with real workflow-shell controls and Git history.
Align the isolation overview with delivered Step 2-4 proofs.

ADR: 0024, 0052

Author: cemililik

.github/workflows/ci.yml

@@ -322,7 +322,14 @@ jobs:
           set -euo pipefail
           case "$EVENT_NAME" in
             pull_request) openapi_base="$PR_BASE_SHA"; openapi_head="$PR_HEAD_SHA" ;;
-            push) openapi_base="$PUSH_BEFORE_SHA"; openapi_head="$HEAD_SHA" ;;
+            push)
+              if [[ "$PUSH_BEFORE_SHA" == "0000000000000000000000000000000000000000" ]]; then
+                openapi_base="${HEAD_SHA}^"
+              else
+                openapi_base="$PUSH_BEFORE_SHA"
+              fi
+              openapi_head="$HEAD_SHA"
+              ;;
             workflow_dispatch) openapi_base="$MANUAL_BASE_REF"; openapi_head="$HEAD_SHA" ;;
             *) echo "Unsupported OpenAPI event" >&2; exit 1 ;;
           esac

docs/architecture/09-tenant-isolation.md

@@ -36,8 +36,8 @@ intersected with normal context, filters and RLS. Tenant hosts expose tenant-wid
 rows only; organization hosts add only their own organization's rows. Claim-only,
 ambient and unresolved origins have no public host scope. Publication/access and
 lifecycle remain explicit read predicates. P02d-4 Step 1 delivers host provenance,
-public admission and physical transaction-mode proofs. Endpoint and eligibility
-proofs remain with Steps 2–4;
+public admission and physical transaction-mode proofs. Steps 2–4 delivered endpoint,
+eligibility and contract proofs;
 [ADR-0052](../decisions/0052-anonymous-public-read-boundary.md) owns the boundary.
 
 | Layer | Tenant mechanism | Organization mechanism |

scripts/test-openapi-ci.py

@@ -1,11 +1,14 @@
 #!/usr/bin/env python3
-"""Falsifiable controls for snapshot admission and the one-time bootstrap exception."""
+"""Falsifiable controls for event selection, snapshot admission and bootstrap."""
 import importlib.util
 import json
+import os
 from pathlib import Path
+import re
 import subprocess
 import sys
 import tempfile
+import textwrap
 import unittest
 from unittest.mock import patch
 
@@ -54,6 +57,58 @@ def run(command, **kwargs):
                 '--tool', str(self.root / 'tool'), '--output', str(self.root / 'reports')]), patch.object(ci.subprocess, 'run', side_effect=run):
             return ci.main()
 
+    def select_event(self, event, head, before='', pr_base='', pr_head='', manual_base=''):
+        workflow = (Path(__file__).resolve().parents[1] / '.github/workflows/ci.yml').read_text()
+        selections = re.findall(r'(?m)^          case "\$EVENT_NAME" in\n(?:.*\n)*?          esac\n', workflow)
+        self.assertEqual(1, len(selections), 'Exercise the actual workflow event selector')
+        script = 'set -euo pipefail\n' + textwrap.dedent(selections[0])
+        script += '\nprintf "%s\\n%s\\n" "$openapi_base" "$openapi_head"\n'
+        result = REAL_RUN(['bash', '-c', script], cwd=self.root, check=True, capture_output=True, text=True,
+            env={**os.environ, 'EVENT_NAME': event, 'HEAD_SHA': head, 'PUSH_BEFORE_SHA': before,
+                 'PR_BASE_SHA': pr_base, 'PR_HEAD_SHA': pr_head, 'MANUAL_BASE_REF': manual_base})
+        return result.stdout.splitlines()
+
+    def test_new_branch_push_uses_the_selected_heads_verified_parent(self):
+        parent = self.save(CURRENT)
+        head = self.save({**CURRENT, 'info': {**CURRENT['info'], 'title': 'Selected head'}})
+        self.save({**CURRENT, 'info': {**CURRENT['info'], 'title': 'Later checkout'}})
+        base_ref, head_ref = self.select_event('push', head, before='0' * 40)
+        self.assertEqual(parent, ci.commit(base_ref))
+        self.assertEqual(head, head_ref)
+        self.assertEqual(0, self.run_ci(base_ref, head_ref))
+        recorded = json.loads((self.root / 'reports/commits.json').read_text())
+        self.assertEqual((parent, head, False), (recorded['base'], recorded['head'], recorded['firstBaseline']))
+
+    def test_existing_branch_push_preserves_before_across_multiple_commits(self):
+        before = self.save(CURRENT)
+        self.save({**CURRENT, 'info': {**CURRENT['info'], 'title': 'Intermediate'}})
+        head = self.save({**CURRENT, 'info': {**CURRENT['info'], 'title': 'Head'}})
+        self.assertEqual([before, head], self.select_event('push', head, before=before))
+
+    def test_pull_request_preserves_its_base_and_head(self):
+        head = self.save(CURRENT)
+        self.assertEqual([self.base, head], self.select_event('pull_request', 'unused-runner-head',
+            before='0' * 40, pr_base=self.base, pr_head=head))
+
+    def test_manual_run_preserves_its_explicit_base_ref(self):
+        self.git('branch', 'manual-base', self.base)
+        head = self.save(CURRENT)
+        base_ref, head_ref = self.select_event('workflow_dispatch', head, manual_base='manual-base')
+        self.assertEqual('manual-base', base_ref)
+        self.assertEqual(self.base, ci.commit(base_ref))
+        self.assertEqual(head, head_ref)
+
+    def test_unknown_event_is_refused(self):
+        with self.assertRaises(subprocess.CalledProcessError) as error:
+            self.select_event('pull_request_target', self.base)
+        self.assertIn('Unsupported OpenAPI event', error.exception.stderr)
+
+    def test_new_branch_push_without_a_parent_is_refused(self):
+        base_ref, head_ref = self.select_event('push', self.base, before='0' * 40)
+        with patch.object(ci, 'bootstrap') as bootstrap, self.assertRaises(subprocess.CalledProcessError):
+            self.run_ci(base_ref, head_ref)
+        bootstrap.assert_not_called()
+
     def test_missing_head_snapshot_is_refused_before_bootstrap(self):
         with patch.object(ci, 'bootstrap') as bootstrap, self.assertRaisesRegex(ValueError, 'Head snapshot'):
             self.run_ci(self.base, self.base)