Complete Phase 2 handoff migration for release-run and sync

Author: fraware

examples/pcs_qc_release/release/handoff/handoff_for_pf.json

@@ -0,0 +1,31 @@
+{
+  "created_at": "2026-05-17T21:22:22Z",
+  "expected_outputs": {
+    "signed_science_claim_bundle.json": {
+      "artifact_type": "SignedScienceClaimBundle.v0"
+    },
+    "verification_result.json": {
+      "artifact_type": "VerificationResult.v0"
+    }
+  },
+  "from_component": "LabTrust-Gym",
+  "handoff_id": "handoff-labtrust-to-pf-qc-release-v0.1",
+  "handoff_kind": "bundle_to_verifier",
+  "input_artifacts": {
+    "science_claim_bundle.certified.json": {
+      "artifact_type": "ScienceClaimBundle.v0",
+      "sha256": "sha256:9b42d792199eb6f358d26f822699f0ed65bb4366eee306d4958d42121c656833"
+    }
+  },
+  "invariants": {
+    "certificate_id": "cert-trace-886c95f0-5d63-42d6-aa13-5891c12c5a6a",
+    "certified_bundle_hash": "sha256:9b42d792199eb6f358d26f822699f0ed65bb4366eee306d4958d42121c656833",
+    "trace_hash": "sha256:c3e8a3dc4ad86d533de1dfa4ae7fe2a338c2cff3c945404c96a75216524d58cd"
+  },
+  "schema_version": "v0",
+  "signature_or_digest": "sha256:21421c76e5307b056f6f8b6f4ad39abdd1bbddeeba6263dd9790f6da3074adf1",
+  "source_commit": "4c5439ae358733f9a4c4a58e33fdaed1ab0d29de",
+  "source_repo": "https://github.com/fraware/LabTrust-Gym",
+  "status": "Validated",
+  "to_component": "Provability Fabric"
+}

examples/pcs_qc_release/release/handoff/handoff_to_pf.json

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import json
 import subprocess
 import sys
 from pathlib import Path
@@ -31,6 +32,13 @@ def main() -> int:
         subprocess.run(["pcs", "validate", str(path)], check=True, cwd=ROOT)
         print("OK pcs validate", artifact)
 
+    fragment = release / "labtrust_release_fragment.json"
+    if fragment.is_file():
+        from labtrust_gym.pcs.release_fragment import assert_release_fragment_valid
+
+        assert_release_fragment_valid(json.loads(fragment.read_text(encoding="utf-8")))
+        print("OK labtrust_release_fragment.json")
+
     subprocess.run(
         [
             sys.executable,

examples/pcs_qc_release/scripts/ci_validate_release_fixtures.py

@@ -52,7 +52,7 @@ def main() -> int:
     handoff_id = args.handoff_id.strip() or None
     write_run_manifests(run_dir, commits, generator=args.generator, handoff_id=handoff_id)
     print(f"OK {run_dir.name}/RELEASE_HANDOFF_MANIFEST.json")
-    print(f"OK {run_dir.name}/handoff_for_pf.json")
+    print(f"OK {run_dir.name}/handoff_to_pf.json")
     print(f"OK {run_dir.name}/RELEASE_FIXTURE_MANIFEST.json")
 
     if not args.no_promote:

examples/pcs_qc_release/scripts/finalize_release_run.py

@@ -89,18 +89,19 @@ Step "LabTrust-Gym: attach certificate"
 $PfCmd = Get-Command $PfBin -ErrorAction SilentlyContinue
 if (-not $PfCmd) { throw "Provability Fabric CLI not found: $PfBin" }
 
-Step "LabTrust: write PF handoff guard (release-run manifests)"
+Step "LabTrust: write PF HandoffManifest.v0 (release-run manifests)"
 & $Python (Join-Path $PSScriptRoot "finalize_release_run.py") --run-dir $Work --no-promote
 
 Step "Provability Fabric: verify and sign (handoff certified bundle)"
 & $Python -c @"
 from pathlib import Path
-from labtrust_gym.pcs.release_run import HANDOFF_FOR_PF_NAME, validate_handoff_directory
+from labtrust_gym.pcs.handoff_manifest import HANDOFF_TO_PF_NAME
+from labtrust_gym.pcs.release_run import validate_handoff_directory
 import json
 work = Path(r'$Work')
 validate_handoff_directory(work)
-guard = json.loads((work / HANDOFF_FOR_PF_NAME).read_text(encoding='utf-8'))
-print('OK PF input', guard['certified_bundle'], guard['expected_certificate_id'])
+handoff = json.loads((work / HANDOFF_TO_PF_NAME).read_text(encoding='utf-8'))
+print('OK PF input science_claim_bundle.certified.json', handoff['invariants']['certificate_id'])
 "@
 
 & $PfBin verify science-claim $CertifiedJson --out $VerificationJson

examples/pcs_qc_release/scripts/run_pcs_v01_clean_chain.ps1

@@ -70,20 +70,22 @@ pcs validate "$CERTIFIED_JSON"
 
 pcs_require_cmd "$PF_BIN"
 
-pcs_step "LabTrust: write PF handoff guard (release-run manifests)"
+pcs_step "LabTrust: write PF HandoffManifest.v0 (release-run manifests)"
 python "$SCRIPT_DIR/finalize_release_run.py" --run-dir "$WORK" --no-promote
 
 pcs_step "Provability Fabric: verify and sign (handoff certified bundle)"
 python -c "
 from pathlib import Path
-from labtrust_gym.pcs.release_run import HANDOFF_FOR_PF_NAME, validate_handoff_directory
+from labtrust_gym.pcs.handoff_manifest import HANDOFF_TO_PF_NAME
+from labtrust_gym.pcs.release_run import validate_handoff_directory
 work = Path('$WORK')
 validate_handoff_directory(work)
-guard = __import__('json').loads((work / HANDOFF_FOR_PF_NAME).read_text())
-cert = work / guard['certified_bundle']
+handoff = __import__('json').loads((work / HANDOFF_TO_PF_NAME).read_text())
+cert_name = 'science_claim_bundle.certified.json'
+cert = work / cert_name
 if not cert.is_file():
     raise SystemExit(f'missing PF input bundle: {cert}')
-print('OK PF input', cert.name, 'certificate_id', guard['expected_certificate_id'])
+print('OK PF input', cert.name, 'certificate_id', handoff['invariants']['certificate_id'])
 "
 
 "$PF_BIN" verify science-claim "$CERTIFIED_JSON" --out "$VERIFICATION_JSON"

examples/pcs_qc_release/scripts/run_pcs_v01_clean_chain.sh

@@ -9,12 +9,11 @@
 from labtrust_gym.config import get_repo_root
 from labtrust_gym.pcs.manifest import validate_release_manifest
 from labtrust_gym.pcs.release_provenance import validate_release_artifact_provenance
-from labtrust_gym.pcs.handoff_manifest import HANDOFF_TO_PF_NAME
 from labtrust_gym.pcs.release_fragment import LABTRUST_RELEASE_FRAGMENT_NAME
 from labtrust_gym.pcs.release_protocol import assert_no_legacy_pf_handoff
 from labtrust_gym.pcs.release_handoff import verify_release_handoff
 from labtrust_gym.pcs.release_run import (
-    HANDOFF_FOR_PF_NAME,
+    HANDOFF_TO_PF_NAME,
     RELEASE_HANDOFF_MANIFEST_NAME,
     validate_certificate_id_chain,
     validate_handoff_directory,
@@ -178,10 +177,13 @@ def validate_release_fixtures(directory: Path | None = None) -> list[str]:
 
     handoff_root = root / "handoff"
     if handoff_root.is_dir():
+        from labtrust_gym.pcs.release_protocol import assert_no_legacy_handoff_subdir_guard
+
+        assert_no_legacy_handoff_subdir_guard(handoff_root)
         validate_handoff_directory(handoff_root)
         ok.append("handoff/")
-        if (handoff_root / HANDOFF_FOR_PF_NAME).is_file():
-            ok.append(f"handoff/{HANDOFF_FOR_PF_NAME}")
+        if (handoff_root / HANDOFF_TO_PF_NAME).is_file():
+            ok.append(f"handoff/{HANDOFF_TO_PF_NAME}")
         if (handoff_root / RELEASE_HANDOFF_MANIFEST_NAME).is_file():
             ok.append(f"handoff/{RELEASE_HANDOFF_MANIFEST_NAME}")
 

src/labtrust_gym/pcs/release_fixtures.py

@@ -15,6 +15,17 @@
 )
 
 LEGACY_PF_HANDOFF_NAME = "pf_handoff.json"
+LEGACY_HANDOFF_SUBDIR_GUARD = "handoff_for_pf.json"
+
+
+def assert_no_legacy_handoff_subdir_guard(handoff_root: Path) -> None:
+    """``release/handoff/`` must use HandoffManifest.v0, not legacy guard JSON."""
+    legacy = handoff_root.resolve() / LEGACY_HANDOFF_SUBDIR_GUARD
+    if legacy.is_file():
+        raise ValueError(
+            f"handoff/ must not contain legacy {LEGACY_HANDOFF_SUBDIR_GUARD}; "
+            f"use {HANDOFF_TO_PF_NAME}"
+        )
 
 
 def assert_no_legacy_pf_handoff(release_root: Path) -> None:

src/labtrust_gym/pcs/release_protocol.py

@@ -34,7 +34,8 @@
 )
 
 RELEASE_HANDOFF_MANIFEST_NAME = "RELEASE_HANDOFF_MANIFEST.json"
-HANDOFF_FOR_PF_NAME = "handoff_for_pf.json"
+HANDOFF_TO_PF_NAME = "handoff_to_pf.json"
+HANDOFF_FOR_PF_NAME = HANDOFF_TO_PF_NAME  # deprecated alias
 RELEASE_FIXTURE_MANIFEST_NAME = "RELEASE_FIXTURE_MANIFEST.json"
 LEGACY_MANIFEST_NAME = "manifest.json"
 
@@ -196,16 +197,19 @@ def build_handoff_manifest(
     return manifest
 
 
-def build_handoff_for_pf(run_dir: Path) -> dict[str, Any]:
-    certified = _load_json(run_dir / "science_claim_bundle.certified.json")
-    _, certificate_id, trace_hash = certified_bundle_ids(certified)
-    return {
-        "schema_version": "v0",
-        "certified_bundle": "science_claim_bundle.certified.json",
-        "expected_certificate_id": certificate_id,
-        "expected_trace_hash": trace_hash,
-        "expected_bundle_id": certified["bundle_id"],
-    }
+def build_handoff_for_pf(
+    run_dir: Path,
+    *,
+    source_commit: str | None = None,
+) -> dict[str, Any]:
+    """Build HandoffManifest.v0 for PF signing (legacy name retained for callers)."""
+    from labtrust_gym.pcs.handoff_manifest import build_bundle_to_verifier_handoff
+
+    return build_bundle_to_verifier_handoff(
+        run_dir / "science_claim_bundle.certified.json",
+        release_mode=True,
+        source_commit=source_commit,
+    )
 
 
 def build_release_fixture_manifest(
@@ -248,7 +252,7 @@ def write_run_manifests(
     generator: str,
     handoff_id: str | None = None,
 ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
-    """Write RELEASE_HANDOFF_MANIFEST, handoff_for_pf, and RELEASE_FIXTURE_MANIFEST into run_dir."""
+    """Write RELEASE_HANDOFF_MANIFEST, HandoffManifest.v0, and RELEASE_FIXTURE_MANIFEST into run_dir."""
     for name in HANDOFF_ARTIFACTS:
         if not (run_dir / name).is_file():
             raise FileNotFoundError(f"release-run missing handoff artifact: {name}")
@@ -258,7 +262,7 @@ def write_run_manifests(
     handoff_manifest = build_handoff_manifest(
         run_dir, commits, generator=generator, handoff_id=handoff_id
     )
-    handoff_pf = build_handoff_for_pf(run_dir)
+    handoff_pf = build_handoff_for_pf(run_dir, source_commit=commits["labtrust_gym_commit"])
     fixture_manifest = build_release_fixture_manifest(
         run_dir, commits, handoff_manifest, generator=generator
     )
@@ -309,16 +313,30 @@ def validate_handoff_directory(handoff_root: Path) -> None:
         path = handoff_root / name
         if file_content_digest(path) != expected_digest:
             raise ValueError(f"handoff digest mismatch for {name}")
-    pf_guard = handoff_root / HANDOFF_FOR_PF_NAME
-    if not pf_guard.is_file():
-        raise FileNotFoundError(f"handoff missing: {HANDOFF_FOR_PF_NAME}")
-    pf_doc = _load_json(pf_guard)
-    certified = _load_json(handoff_root / pf_doc["certified_bundle"])
+    from labtrust_gym.pcs.handoff_manifest import assert_handoff_manifest_valid
+
+    handoff_path = handoff_root / HANDOFF_TO_PF_NAME
+    if not handoff_path.is_file():
+        raise FileNotFoundError(f"handoff missing: {HANDOFF_TO_PF_NAME}")
+    legacy_guard = handoff_root / "handoff_for_pf.json"
+    if legacy_guard.is_file() and legacy_guard != handoff_path:
+        raise ValueError(
+            "handoff/ must not contain legacy handoff_for_pf.json; use handoff_to_pf.json"
+        )
+    pf_doc = _load_json(handoff_path)
+    assert_handoff_manifest_valid(pf_doc)
+    certified_name = "science_claim_bundle.certified.json"
+    certified = _load_json(handoff_root / certified_name)
     _, cert_id, trace_hash = certified_bundle_ids(certified)
-    if pf_doc["expected_certificate_id"] != cert_id:
-        raise ValueError("handoff_for_pf.expected_certificate_id mismatch")
-    if pf_doc["expected_trace_hash"] != trace_hash:
-        raise ValueError("handoff_for_pf.expected_trace_hash mismatch")
+    inv = pf_doc.get("invariants") or {}
+    if inv.get("certificate_id") != cert_id:
+        raise ValueError("handoff_to_pf invariants.certificate_id mismatch")
+    if inv.get("trace_hash") != trace_hash:
+        raise ValueError("handoff_to_pf invariants.trace_hash mismatch")
+    entry = (pf_doc.get("input_artifacts") or {}).get(certified_name) or {}
+    on_disk = file_content_digest(handoff_root / certified_name)
+    if entry.get("sha256") != on_disk:
+        raise ValueError("handoff_to_pf input_artifacts certified bundle sha256 mismatch")
 
 
 def promote_release_run_atomic(

src/labtrust_gym/pcs/release_run.py

@@ -23,11 +23,9 @@
 )
 from labtrust_gym.pcs.release_run import (
     HANDOFF_ARTIFACTS,
-    HANDOFF_FOR_PF_NAME,
     RELEASE_FIXTURE_MANIFEST_NAME,
     RELEASE_HANDOFF_MANIFEST_NAME,
     DOWNSTREAM_ARTIFACTS,
-    build_handoff_for_pf,
     build_handoff_manifest,
     file_content_digest,
     certified_bundle_ids,
@@ -40,6 +38,26 @@
     RELEASE_FIXTURE_MANIFEST_NAME,
 )
 
+_RELEASE_README_PATHS: tuple[str, ...] = ("README.md", "handoff/README.md")
+
+
+def _preserve_release_readmes(release_root: Path) -> dict[str, str]:
+    preserved: dict[str, str] = {}
+    release_root = release_root.resolve()
+    for rel in _RELEASE_README_PATHS:
+        path = release_root / rel
+        if path.is_file():
+            preserved[rel] = path.read_text(encoding="utf-8")
+    return preserved
+
+
+def _restore_release_readmes(release_root: Path, preserved: dict[str, str]) -> None:
+    release_root = release_root.resolve()
+    for rel, text in preserved.items():
+        path = release_root / rel
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+
 
 def pcs_core_labtrust_release_dir(labtrust_root: Path | None = None) -> Path:
     root = labtrust_root or get_repo_root()
@@ -382,24 +400,29 @@ def sync_release_from_pcs_core_rc(
         json.dumps(handoff_manifest, indent=2, sort_keys=True) + "\n",
         encoding="utf-8",
     )
-    (handoff_staging / HANDOFF_FOR_PF_NAME).write_text(
-        json.dumps(build_handoff_for_pf(staging), indent=2, sort_keys=True) + "\n",
-        encoding="utf-8",
-    )
-
     build_canonical_release_manifest(
         staging,
         handoff_manifest,
         generator=generator,
         certifyedge_bin="certifyedge",
         certifyedge_spec="CertifyEdge/templates/hospital_lab/qc_release.stl",
     )
-    build_pf_handoff(staging, _load(staging / "manifest.json"))
+    manifest = _load(staging / "manifest.json")
+    build_pf_handoff(staging, manifest)
     write_trace_hash_alignment(staging)
 
+    from labtrust_gym.pcs.handoff_manifest import build_handoff_to_pf_from_release
+
+    build_handoff_to_pf_from_release(handoff_staging, manifest)
+    legacy_handoff_guard = handoff_staging / "handoff_for_pf.json"
+    if legacy_handoff_guard.is_file():
+        legacy_handoff_guard.unlink()
+
+    readmes = _preserve_release_readmes(local)
     if local.exists():
         shutil.rmtree(local)
     shutil.move(str(staging), str(local))
+    _restore_release_readmes(local, readmes)
 
     assert_release_matches_pcs_core_rc(local, canon)
     verify_release_handoff(local)