wip(k1): checkpoint connection recovery rewrite

Capture the current unreleased K1 connection, recovery, lifecycle, viewer, and test work as a single known-bad baseline for subsequent fixes.

tests/test_viewer_diagnostics_api.py

@@ -130,11 +130,16 @@ def test_private_scanner_diagnostics_are_durable_structured_and_bounded(
 def test_live_viewer_diagnostic_endpoint_accepts_only_bounded_events(
     caplog: pytest.LogCaptureFixture,
 ) -> None:
-    router = build_viewer_diagnostics_router()
+    expected_build = "/assets/index-abcdefgh.js"
+    router = build_viewer_diagnostics_router(expected_ui_build_id=lambda: expected_build)
     endpoint = _endpoint(router, "/api/v1/viewer/live-diagnostics", "POST")
     event = LiveViewerDiagnosticEvent(
-        schema_version="missioncore.live-viewer-diagnostic/v1",
+        schema_version="missioncore.live-viewer-diagnostic/v2",
         event_code="live_receiver_stalled",
+        ui_build_id=expected_build,
+        document_instance_id="00000000-0000-4000-8000-000000000001",
+        viewer_instance_id="00000000-0000-4000-8000-000000000002",
+        lifecycle_generation=4,
         failure_stage="receiver-stalled",
         stream_id="acquisition-123",
         backend_activity_sequence=8_572,
@@ -150,8 +155,12 @@ def test_live_viewer_diagnostic_endpoint_accepts_only_bounded_events(
         response = endpoint(event)
 
     assert response.status_code == 204
+    assert response.headers["x-missioncore-ui-build"] == expected_build
     assert "event=live_receiver_stalled" in caplog.text
     assert caplog.records[-1].failure_stage == "receiver-stalled"
+    assert caplog.records[-1].document_instance_id == event.document_instance_id
+    assert caplog.records[-1].viewer_instance_id == event.viewer_instance_id
+    assert caplog.records[-1].lifecycle_generation == 4
     with pytest.raises(ValidationError):
         LiveViewerDiagnosticEvent.model_validate(
             {
@@ -160,9 +169,91 @@ def test_live_viewer_diagnostic_endpoint_accepts_only_bounded_events(
             }
         )
     fallback = LiveViewerDiagnosticEvent(
-        schema_version="missioncore.live-viewer-diagnostic/v1",
+        schema_version="missioncore.live-viewer-diagnostic/v2",
         event_code="live_receiver_active_store_admitted",
+        ui_build_id=expected_build,
+        document_instance_id="00000000-0000-4000-8000-000000000001",
+        viewer_instance_id="00000000-0000-4000-8000-000000000002",
+        lifecycle_generation=4,
         stream_id="acquisition-123",
         backend_activity_sequence=8_573,
     )
     assert fallback.failure_stage is None
+
+
+def test_live_viewer_diagnostic_rejects_stale_build_before_logging(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    expected_build = "/assets/index-ijklmnop.js"
+    router = build_viewer_diagnostics_router(expected_ui_build_id=lambda: expected_build)
+    endpoint = _endpoint(router, "/api/v1/viewer/live-diagnostics", "POST")
+    event = LiveViewerDiagnosticEvent(
+        schema_version="missioncore.live-viewer-diagnostic/v2",
+        event_code="live_receiver_error",
+        ui_build_id="/assets/index-abcdefgh.js",
+        document_instance_id="00000000-0000-4000-8000-000000000001",
+        viewer_instance_id="00000000-0000-4000-8000-000000000002",
+        lifecycle_generation=1,
+    )
+
+    with caplog.at_level(
+        logging.INFO,
+        logger="k1link.device_plugins.xgrids_k1.viewer_receiver",
+    ):
+        response = endpoint(event)
+
+    assert response.status_code == 409
+    assert response.headers["x-missioncore-ui-build"] == expected_build
+    assert "Mission Core live Rerun receiver diagnostic" not in caplog.text
+
+
+def test_live_viewer_client_contract_is_no_store_and_exact_build() -> None:
+    expected_build = "/assets/index-abcdefgh.js"
+    router = build_viewer_diagnostics_router(expected_ui_build_id=lambda: expected_build)
+    endpoint = _endpoint(router, "/api/v1/viewer/client-contract", "GET")
+
+    response = endpoint()
+
+    assert response.status_code == 200
+    assert response.headers["cache-control"] == "no-store"
+    assert response.headers["x-missioncore-ui-build"] == expected_build
+    assert json.loads(response.body) == {
+        "schema_version": "missioncore.live-viewer-client-contract/v1",
+        "status": "ready",
+        "ui_build_id": expected_build,
+        "diagnostic_schema_version": "missioncore.live-viewer-diagnostic/v2",
+    }
+
+
+def test_live_viewer_client_contract_no_dist_is_retryable_without_reload_header() -> None:
+    router = build_viewer_diagnostics_router(expected_ui_build_id=lambda: None)
+    endpoint = _endpoint(router, "/api/v1/viewer/client-contract", "GET")
+
+    response = endpoint()
+
+    assert response.status_code == 503
+    assert response.headers["cache-control"] == "no-store"
+    assert "x-missioncore-ui-build" not in response.headers
+    assert json.loads(response.body) == {
+        "schema_version": "missioncore.live-viewer-client-contract/v1",
+        "status": "frontend-build-unavailable",
+    }
+
+
+def test_development_viewer_diagnostics_do_not_reload_against_dist_build() -> None:
+    router = build_viewer_diagnostics_router(
+        expected_ui_build_id=lambda: "/assets/index-abcdefgh.js",
+    )
+    endpoint = _endpoint(router, "/api/v1/viewer/live-diagnostics", "POST")
+    event = LiveViewerDiagnosticEvent(
+        schema_version="missioncore.live-viewer-diagnostic/v2",
+        event_code="live_receiver_active_store_admitted",
+        ui_build_id="development",
+        document_instance_id="00000000-0000-4000-8000-000000000001",
+        viewer_instance_id="00000000-0000-4000-8000-000000000002",
+        lifecycle_generation=1,
+    )
+
+    response = endpoint(event)
+
+    assert response.status_code == 204