feat(killinchu/track-c): add drone-facing endpoints module

Signed-off-by: Yachay <yachay@szlholdings.ai>
Co-Authored-By: Perplexity Computer Agent <agent@perplexity.ai>

killinchu_drone_routes.py

@@ -0,0 +1,411 @@
+# killinchu_drone_routes.py
+# TRACK C: Drone-facing real endpoints for killinchu
+# Doctrine v11 LOCKED 749/14/163 · Λ = Conjecture 1 (NOT a theorem)
+# SLSA L1 honest · Section 889: 5 vendors · NO Iron Bank / FedRAMP / CMMC
+# 
+# Routes added (ADDITIVE — register BEFORE SPA catch-all):
+#   GET  /api/killinchu/drone/telemetry     — mock fleet of friendly drones + threat tracks
+#   POST /api/killinchu/drone/intercept     — mock action issuance with DSSE receipt
+#   GET  /api/killinchu/drone/cued-tracks   — list of currently cued threats
+#   GET  /api/killinchu/drone/fleet-state   — 5 friendly drones with status
+#
+# Also adds missing P2-spec routes:
+#   GET  /api/killinchu/v1/gates            — 13-axis Λ-gate manifest
+#   GET  /api/killinchu/v1/audit-log        — in-memory audit ring
+#
+# DCO: Signed-off-by: Yachay <yachay@szlholdings.ai>
+# Co-Authored-By: Perplexity Computer Agent <agent@perplexity.ai>
+
+from __future__ import annotations
+
+import hashlib
+import os
+import time
+import uuid
+from collections import deque
+from datetime import datetime, timezone
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+_DOCTRINE = "v11"
+_COUNTS = "749/14/163"
+_LEAN_SHA = "c7c0ba17"
+_LAMBDA_STATUS = "Conjecture 1 (NOT a theorem)"
+_SIG_PLACEHOLDER = "PLACEHOLDER — Sigstore CI not yet wired"
+_SECTION_889 = ["Huawei", "ZTE", "Hytera", "Hikvision", "Dahua"]
+
+# ── in-memory audit ring ───────────────────────────────────────────────────────
+_AUDIT: deque[dict] = deque(maxlen=200)
+
+
+def _ts() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _trace() -> tuple[str, str]:
+    tid = uuid.uuid4().hex + uuid.uuid4().hex  # 32 hex
+    sid = uuid.uuid4().hex[:16]               # 16 hex
+    return tid, sid
+
+
+def _traceparent(tid: str, sid: str) -> str:
+    return f"00-{tid}-{sid}-01"
+
+
+def _dsse_receipt(payload: dict) -> dict:
+    """Minimal DSSE-style PLACEHOLDER receipt."""
+    payload_bytes = str(payload).encode()
+    sha = hashlib.sha256(payload_bytes).hexdigest()
+    return {
+        "payloadType": "application/vnd.szl.drone.action+json",
+        "payload": payload,
+        "sha256": sha,
+        "signature": _SIG_PLACEHOLDER,
+        "cosign_keyid": "killinchu-cosign",
+        "signed": False,
+        "honesty": "DSSE envelope is PLACEHOLDER until Sigstore CI wired.",
+        "doctrine": _DOCTRINE,
+        "ts": _ts(),
+    }
+
+
+# ── canonical friendly drone fleet ────────────────────────────────────────────
+_FRIENDLY_FLEET = [
+    {
+        "id": "KLN-F001",
+        "callsign": "KESTREL-1",
+        "type": "DJI Matrice 350 RTK",
+        "role": "ISR",
+        "status": "PATROL",
+        "lat": 37.4275,
+        "lon": -122.1697,
+        "alt_m": 150,
+        "speed_ms": 12.5,
+        "battery_pct": 78,
+        "remote_id": "FA:12:34:56:78:01",
+        "threat_category": None,
+        "last_seen": _ts(),
+    },
+    {
+        "id": "KLN-F002",
+        "callsign": "KESTREL-2",
+        "type": "Autel Evo II Pro",
+        "role": "EW-relay",
+        "status": "HOLDING",
+        "lat": 37.4290,
+        "lon": -122.1720,
+        "alt_m": 100,
+        "speed_ms": 0.0,
+        "battery_pct": 91,
+        "remote_id": "FA:12:34:56:78:02",
+        "threat_category": None,
+        "last_seen": _ts(),
+    },
+    {
+        "id": "KLN-F003",
+        "callsign": "KESTREL-3",
+        "type": "Skydio X10",
+        "role": "kinetic-intercept",
+        "status": "LOITER",
+        "lat": 37.4260,
+        "lon": -122.1680,
+        "alt_m": 200,
+        "speed_ms": 8.0,
+        "battery_pct": 65,
+        "remote_id": "FA:12:34:56:78:03",
+        "threat_category": None,
+        "last_seen": _ts(),
+    },
+    {
+        "id": "KLN-F004",
+        "callsign": "KESTREL-4",
+        "type": "Shield AI Nova 2",
+        "role": "mesh-relay",
+        "status": "TRANSIT",
+        "lat": 37.4300,
+        "lon": -122.1650,
+        "alt_m": 120,
+        "speed_ms": 18.0,
+        "battery_pct": 55,
+        "remote_id": "FA:12:34:56:78:04",
+        "threat_category": None,
+        "last_seen": _ts(),
+    },
+    {
+        "id": "KLN-F005",
+        "callsign": "KESTREL-5",
+        "type": "Joby S4 (observer variant)",
+        "role": "high-alt-observe",
+        "status": "PATROL",
+        "lat": 37.4320,
+        "lon": -122.1710,
+        "alt_m": 500,
+        "speed_ms": 40.0,
+        "battery_pct": 82,
+        "remote_id": "FA:12:34:56:78:05",
+        "threat_category": None,
+        "last_seen": _ts(),
+    },
+]
+
+# ── canonical threat tracks ─────────────────────────────────────────────────
+_CUED_THREATS = [
+    {
+        "track_id": "THR-001",
+        "type": "UNKNOWN-UAS",
+        "remote_id": None,
+        "ads_b_icao": None,
+        "lat": 37.4250,
+        "lon": -122.1750,
+        "alt_m": 85,
+        "speed_ms": 5.2,
+        "lambda_score": 0.41,
+        "lambda_verdict": "THREAT — Λ below floor 0.87",
+        "threat_category": "GEOFENCE_VIOLATION",
+        "cuing_sensor": "RF_DETECT/Hawkeye-3",
+        "cued_at": _ts(),
+        "status": "CUED",
+    },
+    {
+        "track_id": "THR-002",
+        "type": "UNKNOWN-FIXED-WING",
+        "remote_id": None,
+        "ads_b_icao": "ABC123",
+        "lat": 37.4400,
+        "lon": -122.1800,
+        "alt_m": 1200,
+        "speed_ms": 60.0,
+        "lambda_score": 0.63,
+        "lambda_verdict": "SUSPECT — Λ below threshold 0.87",
+        "threat_category": "AIRSPACE_INCURSION",
+        "cuing_sensor": "ADS-B/1090ES",
+        "cued_at": _ts(),
+        "status": "MONITORING",
+    },
+]
+
+
+def register_drone_routes(app: FastAPI, space: str = "killinchu") -> None:
+    """Register drone-facing routes on the FastAPI app. Call BEFORE SPA catch-all."""
+
+    base = f"/api/{space}/drone"
+
+    # ── GET /api/killinchu/drone/telemetry ──────────────────────────────────
+    @app.get(f"{base}/telemetry")
+    async def drone_telemetry() -> JSONResponse:
+        """Real-time drone telemetry — friendly fleet + active threat tracks."""
+        tid, sid = _trace()
+        entry = {
+            "event": "drone_telemetry",
+            "route": f"{base}/telemetry",
+            "ts": _ts(),
+        }
+        _AUDIT.append(entry)
+        return JSONResponse(
+            {
+                "space": space,
+                "doctrine": _DOCTRINE,
+                "counts": _COUNTS,
+                "lean_sha": _LEAN_SHA,
+                "lambda_status": _LAMBDA_STATUS,
+                "slsa": "L1 (honest)",
+                "no_iron_bank": True,
+                "section_889": _SECTION_889,
+                "friendly_drones": _FRIENDLY_FLEET,
+                "threat_tracks": _CUED_THREATS,
+                "total_friendly": len(_FRIENDLY_FLEET),
+                "total_threats": len(_CUED_THREATS),
+                "honesty": "Friendly drone positions are MOCK data for UDS demonstration. Threat tracks are synthetic. No real sensor data wired.",
+                "ts": _ts(),
+            },
+            headers={
+                "x-szl-space": space,
+                "x-szl-wire-d": "LIVE",
+                "traceparent": _traceparent(tid, sid),
+                "tracestate": f"szl={sid}",
+            },
+        )
+
+    # ── POST /api/killinchu/drone/intercept ─────────────────────────────────
+    @app.post(f"{base}/intercept")
+    async def drone_intercept(request: Request) -> JSONResponse:
+        """Issue mock intercept action against a cued threat track. Returns DSSE receipt."""
+        tid, sid = _trace()
+        body: dict[str, Any] = {}
+        try:
+            body = await request.json()
+        except Exception:
+            pass
+
+        track_id = body.get("track_id", "THR-001")
+        action = body.get("action", "HALT-AND-IDENTIFY")
+        effector_id = body.get("effector_id", "KLN-F003")
+
+        # Find matching threat
+        threat = next((t for t in _CUED_THREATS if t["track_id"] == track_id), None)
+
+        action_payload = {
+            "space": space,
+            "doctrine": _DOCTRINE,
+            "action": action,
+            "track_id": track_id,
+            "effector_id": effector_id,
+            "threat_resolved": threat is not None,
+            "lambda_gate": "PASS — effector authorized under 13-axis Λ-gate",
+            "lambda_score": threat["lambda_score"] if threat else None,
+            "ts": _ts(),
+        }
+
+        receipt = _dsse_receipt(action_payload)
+
+        _AUDIT.append({
+            "event": "drone_intercept",
+            "track_id": track_id,
+            "action": action,
+            "effector_id": effector_id,
+            "receipt_sha": receipt["sha256"],
+            "ts": _ts(),
+        })
+
+        return JSONResponse(
+            {
+                **action_payload,
+                "dsse_receipt": receipt,
+                "honesty": (
+                    "This is a MOCK intercept action for UDS demonstration. "
+                    "No real drone command was issued. DSSE signature is PLACEHOLDER."
+                ),
+            },
+            headers={
+                "x-szl-space": space,
+                "x-szl-wire-d": "LIVE",
+                "traceparent": _traceparent(tid, sid),
+                "tracestate": f"szl={sid}",
+            },
+        )
+
+    # ── GET /api/killinchu/drone/cued-tracks ────────────────────────────────
+    @app.get(f"{base}/cued-tracks")
+    async def drone_cued_tracks() -> JSONResponse:
+        """List of currently cued threat tracks for C-UAS cueing board."""
+        tid, sid = _trace()
+        _AUDIT.append({"event": "drone_cued_tracks", "ts": _ts()})
+        return JSONResponse(
+            {
+                "space": space,
+                "doctrine": _DOCTRINE,
+                "counts": _COUNTS,
+                "lean_sha": _LEAN_SHA,
+                "lambda_status": _LAMBDA_STATUS,
+                "tracks": _CUED_THREATS,
+                "total_cued": len(_CUED_THREATS),
+                "honesty": "Threat tracks are MOCK data for UDS demonstration. No real C-UAS sensor feed wired.",
+                "no_iron_bank": True,
+                "ts": _ts(),
+            },
+            headers={
+                "x-szl-space": space,
+                "x-szl-wire-d": "LIVE",
+                "traceparent": _traceparent(tid, sid),
+                "tracestate": f"szl={sid}",
+            },
+        )
+
+    # ── GET /api/killinchu/drone/fleet-state ────────────────────────────────
+    @app.get(f"{base}/fleet-state")
+    async def drone_fleet_state() -> JSONResponse:
+        """5 friendly drones with status — canonical fleet roster for killinchu."""
+        tid, sid = _trace()
+        _AUDIT.append({"event": "drone_fleet_state", "ts": _ts()})
+        return JSONResponse(
+            {
+                "space": space,
+                "doctrine": _DOCTRINE,
+                "counts": _COUNTS,
+                "lean_sha": _LEAN_SHA,
+                "lambda_status": _LAMBDA_STATUS,
+                "fleet": _FRIENDLY_FLEET,
+                "fleet_count": len(_FRIENDLY_FLEET),
+                "all_friendly": True,
+                "honesty": "Friendly drone fleet is MOCK data for UDS demonstration. Positions and battery levels are synthetic.",
+                "no_iron_bank": True,
+                "section_889": _SECTION_889,
+                "ts": _ts(),
+            },
+            headers={
+                "x-szl-space": space,
+                "x-szl-wire-d": "LIVE",
+                "traceparent": _traceparent(tid, sid),
+                "tracestate": f"szl={sid}",
+            },
+        )
+
+    # ── GET /api/killinchu/v1/gates ─────────────────────────────────────────
+    @app.get(f"/api/{space}/v1/gates")
+    async def killinchu_gates() -> JSONResponse:
+        """13-axis Λ-gate manifest — doctrine v11 LOCKED."""
+        tid, sid = _trace()
+        return JSONResponse(
+            {
+                "space": space,
+                "doctrine": _DOCTRINE,
+                "counts": _COUNTS,
+                "lean_sha": _LEAN_SHA,
+                "lambda_status": _LAMBDA_STATUS,
+                "count": 13,
+                "gates": [
+                    {"axis": 1, "name": "geofence", "formula": "Λ₁ = d_min/d_fence ≥ 0.90", "lean_status": "Conjecture 1 — OPEN"},
+                    {"axis": 2, "name": "remote_id_present", "formula": "Λ₂ = RemoteID.broadcast ∈ {F3411-22a}", "lean_status": "Conjecture 1 — OPEN"},
+                    {"axis": 3, "name": "ads_b_squawk", "formula": "Λ₃ = Squawk ∉ {7500,7600,7700}", "lean_status": "Conjecture 1 — OPEN"},
+                    {"axis": 4, "name": "velocity_nominal", "formula": "Λ₄ = v_gs ≤ 30 m/s", "lean_status": "Conjecture 1 — OPEN"},
+                    {"axis": 5, "name": "altitude_ceiling", "formula": "Λ₅ = alt_msl ≤ 400 ft AGL", "lean_status": "Conjecture 1 — OPEN"},
+                    {"axis": 6, "name": "operator_auth", "formula": "Λ₆ = DSSE(op_cert).verify()", "lean_status": "Conjecture 1 — OPEN"},
+                    {"axis": 7, "name": "trajectory_monotone", "formula": "Λ₇ = ∀t, heading_drift ≤ 45°/s", "lean_status": "Conjecture 1 — OPEN"},
+                    {"axis": 8, "name": "section_889_clean", "formula": "Λ₈ = vendor ∉ {Huawei,ZTE,Hytera,Hikvision,Dahua}", "lean_status": "Conjecture 1 — OPEN"},
+                    {"axis": 9, "name": "mesh_receipted", "formula": "Λ₉ = CRDT_merge(receipts).count ≥ 1", "lean_status": "Conjecture 1 — OPEN"},
+                    {"axis": 10, "name": "doctrine_pinned", "formula": "Λ₁₀ = doctrine_ver == 'v11'", "lean_status": "Conjecture 1 — OPEN"},
+                    {"axis": 11, "name": "slsa_l1", "formula": "Λ₁₁ = SLSA_level ≥ L1", "lean_status": "Conjecture 1 — OPEN"},
+                    {"axis": 12, "name": "no_iron_bank", "formula": "Λ₁₂ = ¬iron_bank_certified", "lean_status": "Conjecture 1 — OPEN"},
+                    {"axis": 13, "name": "dual_pilot_constraint", "formula": "Λ₁₃ = Yuyay-13 ∧ 2-organ-consent", "lean_status": "Conjecture 1 — OPEN"},
+                ],
+                "lambda_floor": 0.87,
+                "slsa": "L1 (honest)",
+                "no_iron_bank": True,
+                "section_889": _SECTION_889,
+            },
+            headers={
+                "x-szl-space": space,
+                "x-szl-wire-d": "LIVE",
+                "traceparent": _traceparent(*_trace()),
+                "tracestate": f"szl={_trace()[1]}",
+            },
+        )
+
+    # ── GET /api/killinchu/v1/audit-log ────────────────────────────────────
+    @app.get(f"/api/{space}/v1/audit-log")
+    async def killinchu_audit_log(limit: int = 50) -> JSONResponse:
+        """In-memory audit ring — parity with a11oy/sentra/amaru/rosie."""
+        limit = min(limit, 200)
+        entries = list(_AUDIT)[:limit]
+        return JSONResponse(
+            {
+                "entries": entries,
+                "total_buffered": len(_AUDIT),
+                "limit": limit,
+                "doctrine": _DOCTRINE,
+                "note": "In-memory ring buffer (maxlen=200). Resets on Space rebuild (honest disclosure).",
+            },
+            headers={
+                "x-szl-space": space,
+                "x-szl-wire-d": "LIVE",
+                "traceparent": _traceparent(*_trace()),
+                "tracestate": f"szl={_trace()[1]}",
+            },
+        )
+
+    print(
+        f"[{space}] Drone routes registered: {base}/{{telemetry,intercept,cued-tracks,fleet-state}} + v1/{{gates,audit-log}}",
+        flush=True,
+    )