Add typed OpenAPI, MELT, and runtime contracts

Dockerfile

@@ -112,6 +112,7 @@ COPY cathedral.html knowledge.json operator_shell_v4.py serve.py szl_evidence_re
 # falls back and /spaces + /api/<ns>/v1/spaces/health 404. Byte-identical a11oy+killinchu.
 COPY szl_spaces_proxy.py szl_spaces_surface.py ./
 COPY szl_live_wires.py live_wires.html live_wires_3d.js szl_rosie_companion.py killinchu_szl_pqc_sign.py szl_rekor.py killinchu_osint.py szl_be_hardening.py szl_unay.py szl_khipu_lmdb.py szl_khipu_replicate.py szl_unay_routes.py szl_warhacker_aliases.py killinchu_genius.py killinchu_warhacker_demos.py killinchu_v3.py szl_brain.py szl_rag.py szl_formulas.py szl_understudy.py ./
+COPY killinchu_public_contracts.py ./
 COPY szl_killinchu_cookbook.py szl_uds_hardening.py killinchu_fusion.py szl_v4_fleet.py szl_ken.py killinchu_frontier_patch.py killinchu_drone_routes.py killinchu_parity.py killinchu_cannonico.py killinchu_elite_console.py killinchu_experience.py _vendor_blobs.py killinchu_fleet_vessels.py killinchu_maritime_risk.py killinchu_maritime_intel.py killinchu_maritime_view.py killinchu_live_feeds.py killinchu_feeds_realdata.py killinchu_asw.py killinchu_anatomy.py killinchu_health_twin.py fleet_vessels_data.json killinchu_beyond.py szl_khipu_consensus.py killinchu_mesh.py killinchu_mesh_view.py killinchu_formula_endpoints.py killinchu_edge_formulas.py killinchu_active_flux.py killinchu_platform_dynamics.py ./
 COPY killinchu_edge_console.py szl_agentic_loop.py szl_anatomy_routes.py szl_formula_wiring.py a11oy_code_engine.py killinchu_ops_control.py szl_llm_registry.py szl_alloy_models.py a11oy_agent_loop.py a11oy_org_rag.py a11oy_mcp_client.py killinchu_mined_ops.py killinchu_resweep_ops.py killinchu_wave910.py killinchu_posture_topology.py szl_connectors_serve.py szl_connector_mcp.py szl_scaling.py szl_allodial.py szl_entanglement.py szl_neuroplasticity.py szl_chain_of_title.py ./
 # Wave 15 frontier organs (Dynamic Linear Attention, Context-Ready Transformer, OPERA perplexity-reward).
@@ -701,4 +702,3 @@ CMD ["python", "serve.py"]
 
 # Build cache-bust 2026-06-07T05:00Z (MINED ops squad): COPY killinchu_mined_ops.py
 # into /app so serve.py can import+register the 4 mined operational/efficiency surfaces.
-

README.md

@@ -467,4 +467,15 @@ One sovereign substrate, many organs — every decision carries a signed, checka
 
 <sub>Doctrine v11 · Λ = Conjecture 1, never green · honest by design · public data only.</sub>
 
+## Public evidence contracts
+
+- `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 /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
+log content. It does not claim an external collector, complete distributed
+traces, model quality, mission readiness, or actuator authority.
+
 Signed-off-by: Stephen P. Lutar Jr. <stephenlutar2@gmail.com>

killinchu_public_contracts.py

@@ -0,0 +1,186 @@
+"""Read-only public contracts for Killinchu runtime and MELT observability.
+
+These endpoints expose measured in-process telemetry and route presence. They
+do not imply model quality, external collector export, operational readiness,
+or authority to actuate a defense system.
+"""
+from __future__ import annotations
+
+import os
+from datetime import datetime, timezone
+from typing import Any
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _has_route(app: Any, path: str, method: str = "GET") -> bool:
+    for route in getattr(getattr(app, "router", None), "routes", []):
+        methods = getattr(route, "methods", set()) or set()
+        if getattr(route, "path", None) == path and method in methods:
+            return True
+    return False
+
+
+def _metrics_snapshot(app: Any) -> dict[str, Any]:
+    try:
+        import szl_metrics_prom
+
+        text = szl_metrics_prom.render(app)
+        families = sorted(
+            {
+                line.split()[2]
+                for line in text.splitlines()
+                if line.startswith("# HELP ") and len(line.split()) >= 3
+            }
+        )
+        samples = [
+            line
+            for line in text.splitlines()
+            if line and not line.startswith("#")
+        ]
+        return {
+            "state": "LIVE_IN_PROCESS",
+            "metric_family_count": len(families),
+            "sample_count": len(samples),
+            "metric_families": families,
+            "source": "/metrics",
+        }
+    except Exception as exc:
+        return {
+            "state": "UNAVAILABLE",
+            "metric_family_count": 0,
+            "sample_count": 0,
+            "metric_families": [],
+            "source": "/metrics",
+            "error_type": type(exc).__name__,
+        }
+
+
+def melt_summary(app: Any, ns: str = "killinchu") -> dict[str, Any]:
+    metrics = _metrics_snapshot(app)
+    metrics_route = _has_route(app, "/metrics")
+    mesh_route = _has_route(app, f"/api/{ns}/v1/mesh/state")
+    live = metrics_route and metrics["state"] == "LIVE_IN_PROCESS"
+    return {
+        "schema": "szl.killinchu.melt-summary/v1",
+        "observed_at": _now(),
+        "transport_state": "REACHABLE",
+        "evidence_state": "LIVE" if live else "UNAVAILABLE",
+        "authority_state": "READ_ONLY",
+        "scope": "MELT runtime observability",
+        "signals": {
+            "metrics": metrics,
+            "events": {
+                "state": "IN_PROCESS",
+                "basis": "request and receipt events remain within the running process unless a durable subsystem records them",
+            },
+            "logs": {
+                "state": "IN_PROCESS",
+                "basis": "structured application logs are emitted by the runtime; no public log corpus is exposed here",
+            },
+            "traces": {
+                "state": "EXPORT_UNAVAILABLE",
+                "basis": "OTLP export is not enabled in this public Space build",
+            },
+        },
+        "contracts": {
+            "metrics_route_registered": metrics_route,
+            "mesh_state_route_registered": mesh_route,
+            "metrics_endpoint": "/metrics",
+            "mesh_endpoint": f"/api/{ns}/v1/mesh/state",
+        },
+        "limits": [
+            "LIVE means measured in this process, not an uptime SLA.",
+            "No external collector, distributed trace completeness, model quality, or business outcome is claimed.",
+            "This endpoint is read-only and performs no effector action.",
+        ],
+    }
+
+
+def runtime_status(app: Any, ns: str = "killinchu") -> dict[str, Any]:
+    route_count = len(getattr(getattr(app, "router", None), "routes", []))
+    return {
+        "schema": "szl.killinchu.runtime-status/v1",
+        "observed_at": _now(),
+        "service": ns,
+        "transport_state": "REACHABLE",
+        "evidence_state": "COMPUTED",
+        "verification_state": "STRUCTURAL_ONLY",
+        "authority_state": "READ_ONLY",
+        "doctrine": {
+            "version": "v11",
+            "locked_core": "749/14/163 @ c7c0ba17",
+            "lambda": "Conjecture 1",
+        },
+        "runtime": {
+            "route_count": route_count,
+            "git_sha": os.getenv("SZL_GIT_SHA", "unknown"),
+            "build_time": os.getenv("SZL_BUILD_TIME", "unknown"),
+        },
+        "contracts": {
+            "experience_manifest": f"/api/{ns}/v1/experience/manifest",
+            "openapi": f"/api/{ns}/v1/openapi.json",
+            "melt": f"/api/{ns}/v1/melt/summary",
+            "metrics": "/metrics",
+            "readiness": f"/api/{ns}/readyz",
+        },
+        "limits": [
+            "Reachability and registered routes do not establish data freshness, model quality, or mission readiness.",
+            "Defense effectors remain simulated and human-controlled.",
+        ],
+    }
+
+
+def register(app: Any, ns: str = "killinchu") -> dict[str, Any]:
+    from starlette.responses import JSONResponse
+    from starlette.routing import Route
+
+    async def _health(_request):
+        payload = runtime_status(app, ns)
+        payload["schema"] = "szl.killinchu.health/v1"
+        return JSONResponse(payload, headers={"Cache-Control": "no-store"})
+
+    async def _status(_request):
+        return JSONResponse(runtime_status(app, ns), headers={"Cache-Control": "no-store"})
+
+    async def _melt(_request):
+        return JSONResponse(melt_summary(app, ns), headers={"Cache-Control": "no-store"})
+
+    routes = [
+        Route("/health", _health, methods=["GET"], name="killinchu_public_health"),
+        Route(
+            f"/api/{ns}/v1/status",
+            _status,
+            methods=["GET"],
+            name="killinchu_public_status",
+        ),
+        Route(
+            f"/api/{ns}/v1/melt/summary",
+            _melt,
+            methods=["GET"],
+            name="killinchu_melt_summary",
+        ),
+    ]
+    existing = {getattr(route, "name", None) for route in app.router.routes}
+    new = [route for route in routes if route.name not in existing]
+    app.router.routes[0:0] = new
+    return {
+        "schema": "szl.killinchu.public-contract-registration/v1",
+        "routes": [route.path for route in new],
+    }
+
+
+if __name__ == "__main__":
+    from fastapi import FastAPI
+
+    candidate = FastAPI()
+    candidate.add_api_route("/metrics", lambda: "", methods=["GET"])
+    candidate.add_api_route(
+        "/api/killinchu/v1/mesh/state", lambda: {}, methods=["GET"]
+    )
+    result = register(candidate)
+    assert len(result["routes"]) == 3
+    assert runtime_status(candidate)["transport_state"] == "REACHABLE"
+    print("SELFTEST OK")

serve.py

@@ -5583,6 +5583,26 @@ except Exception as _kc_wave_e:  # pragma: no cover — never break SPA/other or
 # ============================================================================
 
 
+# Public discovery and MELT contracts. Registered last and front-inserted so
+# they cannot be shadowed by the SPA history route. All endpoints are GET-only.
+try:
+    import killinchu_public_contracts as _killinchu_public_contracts
+
+    _killinchu_public_contracts_status = _killinchu_public_contracts.register(
+        app, ns="killinchu"
+    )
+    print(
+        f"[killinchu] public contracts registered: {_killinchu_public_contracts_status}",
+        file=sys.stderr,
+    )
+except Exception as _killinchu_public_contracts_e:  # pragma: no cover
+    print(
+        f"[killinchu] public contracts NOT registered: {_killinchu_public_contracts_e!r}; "
+        "SPA + existing API unaffected",
+        file=sys.stderr,
+    )
+
+
 if __name__ == "__main__":
     import uvicorn
     port = int(os.environ.get("PORT", "7860"))

szl_be_hardening.py

@@ -640,6 +640,33 @@ def harden(app: Any, organ: str, ns: Optional[str] = None,
                     status_code=500,
                 )
 
+    # FastAPI's default /openapi.json can fail when one legacy route carries an
+    # annotation that Pydantic cannot resolve. The organ endpoint above already
+    # has a bounded, route-by-route fallback. Front-insert aliases so all public
+    # discovery paths use that generator instead of exposing a known 500.
+    try:
+        from starlette.routing import Route
+
+        async def _openapi_alias(_request):
+            value = await _organ_openapi()
+            return JSONResponse(value) if isinstance(value, dict) else value
+
+        aliases = [
+            Route("/openapi.json", _openapi_alias, methods=["GET"], name=f"{organ}_root_openapi"),
+            Route(
+                f"/api/{organ}/v1/openapi.json",
+                _openapi_alias,
+                methods=["GET"],
+                name=f"{organ}_v1_openapi",
+            ),
+        ]
+        app.router.routes[0:0] = aliases
+        report["registered"].extend(
+            ["openapi:/openapi.json", f"openapi:/api/{organ}/v1/openapi.json"]
+        )
+    except Exception as exc:
+        logger.error(f"openapi_aliases_unavailable: {exc!r}")
+
     report["registered"].append(f"openapi:/api/{organ}/openapi.json")
 
     # ---- 9: honest footer -------------------------------------------------

tests/test_public_contracts.py

@@ -0,0 +1,56 @@
+import unittest
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+import killinchu_public_contracts
+import szl_be_hardening
+import szl_metrics_prom
+
+
+class PublicContractTests(unittest.TestCase):
+    def build_app(self):
+        app = FastAPI(title="contract-test", version="1")
+        szl_metrics_prom.register(app, ns="killinchu")
+
+        @app.get("/api/killinchu/v1/mesh/state")
+        async def mesh_state():
+            return {"state": "test"}
+
+        szl_be_hardening.harden(app, organ="killinchu", khipu_path=":memory:")
+        killinchu_public_contracts.register(app, ns="killinchu")
+        return app
+
+    def test_health_status_and_melt_are_typed(self):
+        client = TestClient(self.build_app())
+        health = client.get("/health")
+        self.assertEqual(health.status_code, 200)
+        self.assertEqual(health.json()["transport_state"], "REACHABLE")
+        self.assertEqual(health.json()["authority_state"], "READ_ONLY")
+
+        status = client.get("/api/killinchu/v1/status")
+        self.assertEqual(status.status_code, 200)
+        self.assertEqual(status.json()["schema"], "szl.killinchu.runtime-status/v1")
+
+        melt = client.get("/api/killinchu/v1/melt/summary")
+        self.assertEqual(melt.status_code, 200)
+        self.assertEqual(melt.json()["evidence_state"], "LIVE")
+        self.assertTrue(melt.json()["contracts"]["metrics_route_registered"])
+        self.assertTrue(melt.json()["contracts"]["mesh_state_route_registered"])
+        self.assertEqual(melt.json()["signals"]["traces"]["state"], "EXPORT_UNAVAILABLE")
+
+    def test_all_openapi_discovery_paths_avoid_legacy_500(self):
+        client = TestClient(self.build_app())
+        for path in (
+            "/openapi.json",
+            "/api/killinchu/openapi.json",
+            "/api/killinchu/v1/openapi.json",
+        ):
+            with self.subTest(path=path):
+                response = client.get(path)
+                self.assertEqual(response.status_code, 200)
+                self.assertEqual(response.json()["openapi"], "3.1.0")
+
+
+if __name__ == "__main__":
+    unittest.main()