Conform source attestation to estate v1 contract

README.md

@@ -472,7 +472,7 @@ One sovereign substrate, many organs — every decision carries a signed, checka
 - `GET /health` - typed read-only health contract; reachability is not readiness.
 - `GET /api/killinchu/v1/status` - runtime, doctrine, and contract discovery.
 - `GET /api/killinchu/v1/melt/summary` - measured in-process MELT summary with explicit external-trace limits.
-- `GET /.well-known/szl-source.json` - honest source attestation that keeps the observed GitHub revision, Hugging Face overlay base, and running Space revision distinct. It currently reports `PENDING_GITHUB_SYNC` and does not claim repository parity.
+- `GET /.well-known/szl-source.json` - estate `szl.deployment-source/v1` contract. It dynamically measures the Hugging Face repository head while explicitly reporting `PENDING_GITHUB_SYNC`; repository-head evidence is not presented as proof of the exact serving process revision or GitHub parity.
 - `GET /openapi.json`, `/api/killinchu/openapi.json`, or `/api/killinchu/v1/openapi.json` - the same generated API description, with bad legacy annotations omitted rather than crashing discovery.
 
 The MELT contract exposes aggregate metric family and sample counts, not private

killinchu_public_contracts.py

@@ -6,16 +6,24 @@ or authority to actuate a defense system.
 """
 from __future__ import annotations
 
+import json
 import os
+import threading
+import time
+import urllib.request
 from datetime import datetime, timezone
 from typing import Any
 
 
 GITHUB_REPOSITORY = "https://github.com/szl-holdings/killinchu"
+GITHUB_REPOSITORY_ID = "szl-holdings/killinchu"
 GITHUB_OBSERVED_REVISION = "dbb7ef1b20b941b299235d13dbd8404eb96cc0a4"
 HF_SPACE_REPOSITORY = "https://huggingface.co/spaces/SZLHOLDINGS/killinchu"
-HF_OVERLAY_BASE_REVISION = "2dd8aaae39bf0ec22959b26cc3c24328f980447c"
+HF_SPACE_ID = "SZLHOLDINGS/killinchu"
+HF_OVERLAY_BASE_REVISION = "fce3a1a581d212119473756d4907a06ff5dc9f2f"
 REVISION_OBSERVED_AT = "2026-07-11T16:16:12.897595+00:00"
+_HF_HEAD_CACHE: dict[str, Any] = {"at": 0.0, "value": None}
+_HF_HEAD_LOCK = threading.Lock()
 
 
 def _now() -> str:
@@ -42,57 +50,114 @@ def _source_git_build_variable() -> dict[str, Any]:
     }
 
 
-def source_attestation() -> dict[str, Any]:
-    """Describe source/deployment revision evidence without claiming parity."""
-    return {
-        "schema": "szl.source-attestation/v1",
-        "observed_at": _now(),
-        "service": "killinchu",
-        "attestation_state": "PENDING_GITHUB_SYNC",
-        "alignment_state": "NOT_VERIFIED",
-        "github_source_observation": {
-            "repository": GITHUB_REPOSITORY,
-            "branch": "main",
-            "revision": GITHUB_OBSERVED_REVISION,
-            "observed_at": REVISION_OBSERVED_AT,
-            "evidence": (
-                "https://api.github.com/repos/szl-holdings/killinchu/commits/"
-                + GITHUB_OBSERVED_REVISION
-            ),
-            "live_branch_head_resolver": (
-                "https://api.github.com/repos/szl-holdings/killinchu/commits/main"
-            ),
-            "semantics": "GitHub main revision observed when this overlay was prepared",
+def _hf_repository_head(force: bool = False) -> dict[str, str] | None:
+    """Resolve the Hub repository head; never label it as the serving process SHA."""
+    now = time.monotonic()
+    with _HF_HEAD_LOCK:
+        cached = _HF_HEAD_CACHE.get("value")
+        if not force and now - float(_HF_HEAD_CACHE["at"]) < 60:
+            return dict(cached) if cached else None
+
+    request = urllib.request.Request(
+        "https://huggingface.co/api/spaces/SZLHOLDINGS/killinchu"
+        "?expand[]=sha&expand[]=lastModified",
+        headers={
+            "User-Agent": "szl-killinchu-source-attestation/2.0",
+            "Accept": "application/json",
         },
-        "huggingface_overlay": {
-            "repository": HF_SPACE_REPOSITORY,
-            "base_revision": HF_OVERLAY_BASE_REVISION,
-            "base_revision_semantics": (
-                "Hugging Face Space revision on which this source-attestation overlay was based"
-            ),
-            "repository_head_state": "RESOLVE_EXTERNALLY",
-            "repository_head_resolver": (
-                "https://huggingface.co/api/spaces/SZLHOLDINGS/killinchu"
-            ),
-            "repository_head_json_field": "sha",
-            "running_process_revision_state": "NOT_EXPOSED_IN_PROCESS",
+    )
+    value: dict[str, str] | None = None
+    try:
+        with urllib.request.urlopen(request, timeout=4) as response:
+            payload = json.load(response)
+        revision = payload.get("sha")
+        last_modified = payload.get("lastModified")
+        if (
+            isinstance(revision, str)
+            and len(revision) == 40
+            and all(char in "0123456789abcdef" for char in revision)
+            and isinstance(last_modified, str)
+            and "T" in last_modified
+        ):
+            value = {
+                "revision": revision,
+                "last_modified": last_modified,
+                "observed_at": _now(),
+            }
+    except Exception:
+        value = None
+
+    with _HF_HEAD_LOCK:
+        _HF_HEAD_CACHE.update({"at": time.monotonic(), "value": value})
+    return dict(value) if value else None
+
+
+def source_attestation(force: bool = False) -> dict[str, Any]:
+    """Emit the estate deployment-source shape without claiming process parity."""
+    head = _hf_repository_head(force=force)
+    if head is None:
+        raise RuntimeError("Hugging Face repository-head evidence is unavailable")
+    return {
+        "schema": "szl.deployment-source/v1",
+        "source": {
+            "repository": GITHUB_REPOSITORY_ID,
+            "commit": GITHUB_OBSERVED_REVISION,
+            "path": "",
         },
-        "build_metadata": {
-            "source_git_revision_variable": _source_git_build_variable(),
+        "deployment": {
+            "hf_space": HF_SPACE_ID,
+            "hf_revision": head["revision"],
         },
-        "relationship": {
-            "state": "PENDING_GITHUB_SYNC",
-            "basis": (
-                "The Hugging Face Space includes overlay commits not yet represented by a "
-                "verified GitHub commit. Repository equality is not claimed."
-            ),
+        "built_at": head["last_modified"],
+        "alignment_state": "PENDING_GITHUB_SYNC",
+        "extensions": {
+            "schema": "szl.killinchu.deployment-source-extension/v1",
+            "deployment_revision_evidence": {
+                "state": "MEASURED",
+                "semantics": (
+                    "Hugging Face repository head measured through the Hub API; it is not "
+                    "proof of the exact revision serving this response during a rolling deploy."
+                ),
+                "resolver": (
+                    "https://huggingface.co/api/spaces/SZLHOLDINGS/killinchu"
+                    "?expand[]=sha&expand[]=lastModified"
+                ),
+                "observed_at": head["observed_at"],
+                "running_process_revision_state": "NOT_EXPOSED_IN_PROCESS",
+            },
+            "source_observation": {
+                "repository_url": GITHUB_REPOSITORY,
+                "branch": "main",
+                "observed_at": REVISION_OBSERVED_AT,
+                "immutable_evidence": (
+                    "https://api.github.com/repos/szl-holdings/killinchu/commits/"
+                    + GITHUB_OBSERVED_REVISION
+                ),
+                "live_branch_head_resolver": (
+                    "https://api.github.com/repos/szl-holdings/killinchu/commits/main"
+                ),
+            },
+            "overlay": {
+                "repository": HF_SPACE_REPOSITORY,
+                "base_revision": HF_OVERLAY_BASE_REVISION,
+                "base_revision_semantics": (
+                    "Hugging Face revision on which this corrective overlay was based"
+                ),
+            },
+            "build_metadata": {
+                "source_git_revision_variable": _source_git_build_variable(),
+                "built_at_semantics": (
+                    "Provider-reported lastModified for deployment.hf_revision; not a "
+                    "verified process start time or reproducible-build attestation."
+                ),
+            },
         },
         "limits": [
-            "The observed GitHub revision is point-in-time evidence, not a live branch-head claim.",
-            "The overlay base revision is not the currently running Hugging Face revision.",
-            "The Hub repository head may lead or lag the process during a rolling deployment, so it is not labeled as the running process revision.",
-            "SZL_GIT_SHA is source build metadata and must not be interpreted as a Hugging Face deployment revision.",
-            "This document is unsigned and does not establish SLSA provenance or binary reproducibility.",
+            "PENDING_GITHUB_SYNC means GitHub/Hugging Face content parity is not claimed.",
+            "deployment.hf_revision is repository-head evidence, not proof of the exact serving process revision.",
+            "source.commit is a point-in-time GitHub source observation, not a live branch-head claim.",
+            "SZL_GIT_SHA remains unverified source build metadata, not the Hugging Face revision.",
+            "This unsigned document does not establish SLSA provenance or binary reproducibility.",
         ],
     }
 
@@ -230,8 +295,22 @@ def register(app: Any, ns: str = "killinchu") -> dict[str, Any]:
         return JSONResponse(melt_summary(app, ns), headers={"Cache-Control": "no-store"})
 
     async def _source_attestation(_request):
+        try:
+            payload = source_attestation(
+                force=_request.query_params.get("refresh") == "1"
+            )
+            status_code = 200
+        except RuntimeError:
+            payload = {
+                "schema": "szl.source-attestation-unavailable/v1",
+                "state": "UNAVAILABLE",
+                "observed_at": _now(),
+                "detail": "Hugging Face repository-head evidence could not be measured.",
+            }
+            status_code = 503
         return JSONResponse(
-            source_attestation(),
+            payload,
+            status_code=status_code,
             headers={"Cache-Control": "no-store", "X-Content-Type-Options": "nosniff"},
         )
 

tests/test_public_contracts.py

@@ -53,34 +53,64 @@ class PublicContractTests(unittest.TestCase):
 
     def test_source_attestation_keeps_source_and_deployment_distinct(self):
         client = TestClient(self.build_app())
-        with patch.dict("os.environ", {"SZL_GIT_SHA": "source-build-sha"}):
+        head = {
+            "revision": "a" * 40,
+            "last_modified": "2026-07-11T16:18:34.000Z",
+            "observed_at": "2026-07-11T16:20:00+00:00",
+        }
+        with patch.dict("os.environ", {"SZL_GIT_SHA": "source-build-sha"}), patch.object(
+            killinchu_public_contracts, "_hf_repository_head", return_value=head
+        ):
             response = client.get("/.well-known/szl-source.json")
         self.assertEqual(response.status_code, 200)
         self.assertEqual(response.headers["cache-control"], "no-store")
         payload = response.json()
-        self.assertEqual(payload["schema"], "szl.source-attestation/v1")
-        self.assertEqual(payload["attestation_state"], "PENDING_GITHUB_SYNC")
-        self.assertEqual(payload["alignment_state"], "NOT_VERIFIED")
-        self.assertEqual(
-            payload["github_source_observation"]["revision"],
-            killinchu_public_contracts.GITHUB_OBSERVED_REVISION,
-        )
+        self.assertEqual(payload["schema"], "szl.deployment-source/v1")
+        self.assertEqual(payload["alignment_state"], "PENDING_GITHUB_SYNC")
         self.assertEqual(
-            payload["huggingface_overlay"]["base_revision"],
-            killinchu_public_contracts.HF_OVERLAY_BASE_REVISION,
+            payload["source"],
+            {
+                "repository": "szl-holdings/killinchu",
+                "commit": killinchu_public_contracts.GITHUB_OBSERVED_REVISION,
+                "path": "",
+            },
         )
         self.assertEqual(
-            payload["huggingface_overlay"]["repository_head_state"],
-            "RESOLVE_EXTERNALLY",
+            payload["deployment"],
+            {"hf_space": "SZLHOLDINGS/killinchu", "hf_revision": "a" * 40},
         )
+        self.assertEqual(payload["built_at"], "2026-07-11T16:18:34.000Z")
+        extension = payload["extensions"]
         self.assertEqual(
-            payload["huggingface_overlay"]["running_process_revision_state"],
+            extension["deployment_revision_evidence"][
+                "running_process_revision_state"
+            ],
             "NOT_EXPOSED_IN_PROCESS",
         )
-        build_variable = payload["build_metadata"]["source_git_revision_variable"]
+        build_variable = extension["build_metadata"]["source_git_revision_variable"]
         self.assertEqual(build_variable["value"], "source-build-sha")
         self.assertFalse(build_variable["is_huggingface_deployment_revision"])
-        self.assertEqual(payload["relationship"]["state"], "PENDING_GITHUB_SYNC")
+
+        # Mirrors the identity checks in check_ecosystem_drift.compare.
+        identity_errors = []
+        if payload.get("schema") != "szl.deployment-source/v1":
+            identity_errors.append("schema")
+        if payload.get("source", {}).get("repository") != "szl-holdings/killinchu":
+            identity_errors.append("source.repository")
+        if payload.get("deployment", {}).get("hf_space") != "SZLHOLDINGS/killinchu":
+            identity_errors.append("deployment.hf_space")
+        if payload.get("deployment", {}).get("hf_revision") != "a" * 40:
+            identity_errors.append("deployment.hf_revision")
+        self.assertEqual(identity_errors, [])
+
+    def test_source_attestation_fails_unknown_instead_of_claiming_stale_head(self):
+        client = TestClient(self.build_app())
+        with patch.object(
+            killinchu_public_contracts, "_hf_repository_head", return_value=None
+        ):
+            response = client.get("/.well-known/szl-source.json?refresh=1")
+        self.assertEqual(response.status_code, 503)
+        self.assertEqual(response.json()["state"], "UNAVAILABLE")
 
     def test_all_openapi_discovery_paths_avoid_legacy_500(self):
         client = TestClient(self.build_app())