Add honest source attestation contract

README.md

@@ -472,6 +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 /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

@@ -11,6 +11,13 @@ from datetime import datetime, timezone
 from typing import Any
 
 
+GITHUB_REPOSITORY = "https://github.com/szl-holdings/killinchu"
+GITHUB_OBSERVED_REVISION = "dbb7ef1b20b941b299235d13dbd8404eb96cc0a4"
+HF_SPACE_REPOSITORY = "https://huggingface.co/spaces/SZLHOLDINGS/killinchu"
+HF_OVERLAY_BASE_REVISION = "2dd8aaae39bf0ec22959b26cc3c24328f980447c"
+REVISION_OBSERVED_AT = "2026-07-11T16:16:12.897595+00:00"
+
+
 def _now() -> str:
     return datetime.now(timezone.utc).isoformat()
 
@@ -23,6 +30,73 @@ def _has_route(app: Any, path: str, method: str = "GET") -> bool:
     return False
 
 
+def _source_git_build_variable() -> dict[str, Any]:
+    value = os.getenv("SZL_GIT_SHA", "unknown")
+    return {
+        "name": "SZL_GIT_SHA",
+        "value": value,
+        "state": "PRESENT_UNVERIFIED" if value != "unknown" else "UNAVAILABLE",
+        "meaning": "operator-supplied source revision build metadata",
+        "verification_state": "UNVERIFIED",
+        "is_huggingface_deployment_revision": False,
+    }
+
+
+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",
+        },
+        "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",
+        },
+        "build_metadata": {
+            "source_git_revision_variable": _source_git_build_variable(),
+        },
+        "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."
+            ),
+        },
+        "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.",
+        ],
+    }
+
+
 def _metrics_snapshot(app: Any) -> dict[str, Any]:
     try:
         import szl_metrics_prom
@@ -116,7 +190,13 @@ def runtime_status(app: Any, ns: str = "killinchu") -> dict[str, Any]:
         },
         "runtime": {
             "route_count": route_count,
-            "git_sha": os.getenv("SZL_GIT_SHA", "unknown"),
+            "source_git_revision_variable": _source_git_build_variable(),
+            "huggingface_revision_evidence": {
+                "running_process_revision_state": "NOT_EXPOSED_IN_PROCESS",
+                "repository_head_state": "RESOLVE_EXTERNALLY",
+                "repository_head_resolver": "https://huggingface.co/api/spaces/SZLHOLDINGS/killinchu",
+                "repository_head_json_field": "sha",
+            },
             "build_time": os.getenv("SZL_BUILD_TIME", "unknown"),
         },
         "contracts": {
@@ -125,6 +205,7 @@ def runtime_status(app: Any, ns: str = "killinchu") -> dict[str, Any]:
             "melt": f"/api/{ns}/v1/melt/summary",
             "metrics": "/metrics",
             "readiness": f"/api/{ns}/readyz",
+            "source_attestation": "/.well-known/szl-source.json",
         },
         "limits": [
             "Reachability and registered routes do not establish data freshness, model quality, or mission readiness.",
@@ -148,6 +229,12 @@ def register(app: Any, ns: str = "killinchu") -> dict[str, Any]:
     async def _melt(_request):
         return JSONResponse(melt_summary(app, ns), headers={"Cache-Control": "no-store"})
 
+    async def _source_attestation(_request):
+        return JSONResponse(
+            source_attestation(),
+            headers={"Cache-Control": "no-store", "X-Content-Type-Options": "nosniff"},
+        )
+
     routes = [
         Route("/health", _health, methods=["GET"], name="killinchu_public_health"),
         Route(
@@ -162,6 +249,12 @@ def register(app: Any, ns: str = "killinchu") -> dict[str, Any]:
             methods=["GET"],
             name="killinchu_melt_summary",
         ),
+        Route(
+            "/.well-known/szl-source.json",
+            _source_attestation,
+            methods=["GET"],
+            name="killinchu_source_attestation",
+        ),
     ]
     existing = {getattr(route, "name", None) for route in app.router.routes}
     new = [route for route in routes if route.name not in existing]
@@ -181,6 +274,6 @@ if __name__ == "__main__":
         "/api/killinchu/v1/mesh/state", lambda: {}, methods=["GET"]
     )
     result = register(candidate)
-    assert len(result["routes"]) == 3
+    assert len(result["routes"]) == 4
     assert runtime_status(candidate)["transport_state"] == "REACHABLE"
     print("SELFTEST OK")

tests/test_public_contracts.py

@@ -1,4 +1,5 @@
 import unittest
+from unittest.mock import patch
 
 from fastapi import FastAPI
 from fastapi.testclient import TestClient
@@ -27,6 +28,17 @@ class PublicContractTests(unittest.TestCase):
         self.assertEqual(health.status_code, 200)
         self.assertEqual(health.json()["transport_state"], "REACHABLE")
         self.assertEqual(health.json()["authority_state"], "READ_ONLY")
+        runtime = health.json()["runtime"]
+        self.assertNotIn("git_sha", runtime)
+        self.assertEqual(
+            runtime["source_git_revision_variable"]["meaning"],
+            "operator-supplied source revision build metadata",
+        )
+        self.assertFalse(
+            runtime["source_git_revision_variable"][
+                "is_huggingface_deployment_revision"
+            ]
+        )
 
         status = client.get("/api/killinchu/v1/status")
         self.assertEqual(status.status_code, 200)
@@ -39,6 +51,37 @@ class PublicContractTests(unittest.TestCase):
         self.assertTrue(melt.json()["contracts"]["mesh_state_route_registered"])
         self.assertEqual(melt.json()["signals"]["traces"]["state"], "EXPORT_UNAVAILABLE")
 
+    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"}):
+            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["huggingface_overlay"]["base_revision"],
+            killinchu_public_contracts.HF_OVERLAY_BASE_REVISION,
+        )
+        self.assertEqual(
+            payload["huggingface_overlay"]["repository_head_state"],
+            "RESOLVE_EXTERNALLY",
+        )
+        self.assertEqual(
+            payload["huggingface_overlay"]["running_process_revision_state"],
+            "NOT_EXPOSED_IN_PROCESS",
+        )
+        build_variable = payload["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")
+
     def test_all_openapi_discovery_paths_avoid_legacy_500(self):
         client = TestClient(self.build_app())
         for path in (