piphi-runtime-kit-python 0.4.3__tar.gz → 0.4.5__tar.gz

{piphi_runtime_kit_python-0.4.3 → piphi_runtime_kit_python-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: piphi-runtime-kit-python
-Version: 0.4.3
+Version: 0.4.5
 Summary: PiPhi Network runtime integration helpers
 Keywords: piphi,runtime,integration,iot
 Author-Email: KelvinSan <support@piphi.network>

{piphi_runtime_kit_python-0.4.3 → piphi_runtime_kit_python-0.4.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "piphi-runtime-kit-python"
-version = "0.4.3"
+version = "0.4.5"
 description = "PiPhi Network runtime integration helpers"
 authors = [
     { name = "KelvinSan", email = "support@piphi.network" },

{piphi_runtime_kit_python-0.4.3 → piphi_runtime_kit_python-0.4.5}/src/piphi_runtime_kit_python/__init__.py

@@ -14,9 +14,13 @@ from .runtime.config_sync import (
     DEFAULT_RUNTIME_VOLUME_DIR,
     RUNTIME_CONFIG_SNAPSHOT_PATH_ENV_NAME,
     ConfigSyncCoordinator,
+    RuntimeConfigRehydrateResult,
+    build_runtime_config_snapshot_from_core_rows,
     build_sync_response,
+    fetch_core_runtime_config_snapshot,
     load_runtime_config_snapshot,
     reconcile_config_ids,
+    rehydrate_runtime_configs,
     resolve_core_base_url,
     resolve_runtime_config_snapshot_path,
 )
@@ -142,6 +146,7 @@ __all__ = [
     "RuntimeConfig",
     "RuntimeConfigApplyResponse",
     "RuntimeConfigRemoveResponse",
+    "RuntimeConfigRehydrateResult",
     "RuntimeConfigSnapshot",
     "RuntimeConfigSyncResponse",
     "RuntimeContext",
@@ -158,6 +163,7 @@ __all__ = [
     "EventTransport",
     "IntegrationEventIngestResponse",
     "IntegrationEventListResponse",
+    "build_runtime_config_snapshot_from_core_rows",
     "build_discovery_response",
     "classify_core_delivery_error",
     "build_core_event_payload",
@@ -180,6 +186,7 @@ __all__ = [
     "dispatch_event_delivery",
     "dispatch_telemetry_delivery",
     "extract_runtime_auth_headers",
+    "fetch_core_runtime_config_snapshot",
     "format_config_apply_log",
     "format_discovery_attempt_log",
     "format_event_log",
@@ -192,6 +199,7 @@ __all__ = [
     "normalize_event_payload",
     "redact_config_secrets",
     "reconcile_config_ids",
+    "rehydrate_runtime_configs",
     "resolve_core_base_url",
     "resolve_runtime_config_snapshot_path",
     "runtime_lifespan",

{piphi_runtime_kit_python-0.4.3 → piphi_runtime_kit_python-0.4.5}/src/piphi_runtime_kit_python/runtime/config_sync.py

@@ -6,9 +6,14 @@ from dataclasses import dataclass
 import json
 import os
 from pathlib import Path
-from typing import Awaitable, Callable, TypeVar
+from typing import Any, Awaitable, Callable, TypeVar
+
+import httpx
 
 from ..schemas import RuntimeConfig, RuntimeConfigSnapshot, RuntimeConfigSyncResponse
+from .auth import build_runtime_auth_headers
+from .context import RuntimeContext
+from .lifespan import DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS
 from .state import RuntimeProcessState
 
 TConfig = TypeVar("TConfig", bound=RuntimeConfig)
@@ -18,6 +23,12 @@ RUNTIME_CONTAINER_ID_ENV_NAME = "PIPHI_CONTAINER_ID"
 RUNTIME_CONFIG_SNAPSHOT_PATH_ENV_NAME = "PIPHI_CONFIG_SNAPSHOT_PATH"
 DEFAULT_RUNTIME_VOLUME_DIR = "/.piphinetwork"
 DEFAULT_RUNTIME_CONFIG_SNAPSHOT_FILENAME = "configs.json"
+CORE_RUNTIME_CONFIG_FETCH_PATH = (
+    "/api/v2/integrations/config/fetch/all/by/container/internal"
+)
+
+
+SnapshotApplyCallable = Callable[[Any], Awaitable[Any]]
 
 
 def resolve_core_base_url(default: str | None = None) -> str | None:
@@ -85,6 +96,226 @@ def load_runtime_config_snapshot(
         return None
 
 
+@dataclass(slots=True)
+class RuntimeConfigRehydrateResult:
+    """Describe what happened during runtime startup config rehydration."""
+
+    snapshot_found: bool = False
+    snapshot_applied: bool = False
+    snapshot_config_count: int = 0
+    snapshot_generation: int | None = None
+    core_attempted: bool = False
+    core_applied: bool = False
+    core_config_count: int = 0
+    core_generation: int | None = None
+    core_error: str | None = None
+    missing_runtime_auth: bool = False
+
+    @property
+    def applied_any(self) -> bool:
+        """Return whether any startup source applied configs."""
+        return self.snapshot_applied or self.core_applied
+
+
+def _model_validate_or_create(model_type: type[Any], payload: dict[str, Any]) -> Any:
+    validator = getattr(model_type, "model_validate", None)
+    if callable(validator):
+        return validator(payload)
+    return model_type(**payload)
+
+
+def _snapshot_validate_or_create(model_type: type[Any], payload: dict[str, Any]) -> Any:
+    validator = getattr(model_type, "model_validate", None)
+    if callable(validator):
+        return validator(payload)
+    return model_type(**payload)
+
+
+def _convert_snapshot_configs(
+    snapshot: RuntimeConfigSnapshot,
+    *,
+    config_model: type[TConfig],
+    snapshot_model: type[Any],
+    reason: str,
+) -> Any:
+    configs = [
+        _model_validate_or_create(config_model, config.model_dump())
+        for config in snapshot.configs
+    ]
+    return _snapshot_validate_or_create(
+        snapshot_model,
+        {
+            "schema_version": snapshot.schema_version,
+            "container_id": snapshot.container_id,
+            "integration_id": snapshot.integration_id,
+            "driver_pid": snapshot.driver_pid,
+            "reason": snapshot.reason or reason,
+            "generation": snapshot.generation,
+            "updated_at": snapshot.updated_at,
+            "configs": configs,
+            "deleted_config_ids": snapshot.deleted_config_ids,
+            "config_hash": snapshot.config_hash,
+            "internal_token": snapshot.internal_token,
+        },
+    )
+
+
+def build_runtime_config_snapshot_from_core_rows(
+    rows: list[dict[str, Any]],
+    *,
+    container_id: str,
+    config_model: type[TConfig] = RuntimeConfig,
+    snapshot_model: type[Any] = RuntimeConfigSnapshot,
+    reason: str = "startup_rehydrate",
+) -> Any:
+    """Build a runtime config snapshot from Core's internal config rows.
+
+    Core returns database-shaped rows where the integration config lives under
+    ``config_data``. This helper turns those rows into the same snapshot shape
+    integrations receive from the normal config-sync endpoint.
+    """
+    configs: list[Any] = []
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        config_data = row.get("config_data")
+        if not isinstance(config_data, dict):
+            continue
+        payload = {**config_data}
+        payload["container_id"] = payload.get("container_id") or container_id
+        configs.append(_model_validate_or_create(config_model, payload))
+
+    return _snapshot_validate_or_create(
+        snapshot_model,
+        {
+            "container_id": container_id,
+            "reason": reason,
+            "configs": configs,
+        },
+    )
+
+
+async def fetch_core_runtime_config_snapshot(
+    *,
+    runtime_context: RuntimeContext,
+    client: httpx.AsyncClient,
+    core_base_url: str | None = None,
+    config_model: type[TConfig] = RuntimeConfig,
+    snapshot_model: type[Any] = RuntimeConfigSnapshot,
+    timeout_seconds: float = DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS,
+    reason: str = "startup_rehydrate",
+) -> Any | None:
+    """Fetch the latest runtime configs from Core using managed-runtime auth."""
+    container_id, internal_token = runtime_context.auth.resolve()
+    if not container_id or not internal_token:
+        return None
+
+    base_url = resolve_core_base_url(core_base_url) or resolve_core_base_url(
+        "http://127.0.0.1:31419"
+    )
+    if not base_url:
+        return None
+
+    response = await client.get(
+        f"{base_url}{CORE_RUNTIME_CONFIG_FETCH_PATH}",
+        params={"container_id": container_id},
+        headers=build_runtime_auth_headers(
+            container_id=container_id,
+            internal_token=internal_token,
+        ),
+        timeout=timeout_seconds,
+    )
+    response.raise_for_status()
+
+    rows = response.json()
+    if not rows:
+        return None
+    if not isinstance(rows, list):
+        raise ValueError("Core runtime config response must be a list.")
+
+    return build_runtime_config_snapshot_from_core_rows(
+        rows,
+        container_id=container_id,
+        config_model=config_model,
+        snapshot_model=snapshot_model,
+        reason=reason,
+    )
+
+
+async def rehydrate_runtime_configs(
+    *,
+    runtime_context: RuntimeContext,
+    client: httpx.AsyncClient,
+    apply_snapshot: SnapshotApplyCallable,
+    config_model: type[TConfig] = RuntimeConfig,
+    snapshot_model: type[Any] = RuntimeConfigSnapshot,
+    core_base_url: str | None = None,
+    timeout_seconds: float = DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS,
+    snapshot_path: str | Path | None = None,
+    snapshot_volume_dir: str | Path = DEFAULT_RUNTIME_VOLUME_DIR,
+    snapshot_reason: str = "startup_snapshot_rehydrate",
+    core_reason: str = "startup_rehydrate",
+    raise_core_errors: bool = False,
+) -> RuntimeConfigRehydrateResult:
+    """Rehydrate runtime configs from the mounted snapshot and then Core.
+
+    Integration authors provide only their config model and apply callback. The
+    SDK handles startup ordering, managed-runtime auth, Core request headers,
+    local snapshot fallback, and safe offline behavior.
+    """
+    result = RuntimeConfigRehydrateResult()
+    container_id = runtime_context.auth.container_id
+
+    cached_snapshot = load_runtime_config_snapshot(
+        path=snapshot_path,
+        container_id=container_id,
+        volume_dir=snapshot_volume_dir,
+    )
+    if cached_snapshot is not None:
+        result.snapshot_found = True
+        snapshot = _convert_snapshot_configs(
+            cached_snapshot,
+            config_model=config_model,
+            snapshot_model=snapshot_model,
+            reason=snapshot_reason,
+        )
+        await apply_snapshot(snapshot)
+        result.snapshot_applied = True
+        result.snapshot_config_count = len(getattr(snapshot, "configs", []) or [])
+        result.snapshot_generation = getattr(snapshot, "generation", None)
+
+    resolved_container_id, resolved_internal_token = runtime_context.auth.resolve()
+    if not resolved_container_id or not resolved_internal_token:
+        result.missing_runtime_auth = True
+        return result
+
+    result.core_attempted = True
+    try:
+        core_snapshot = await fetch_core_runtime_config_snapshot(
+            runtime_context=runtime_context,
+            client=client,
+            core_base_url=core_base_url,
+            config_model=config_model,
+            snapshot_model=snapshot_model,
+            timeout_seconds=timeout_seconds,
+            reason=core_reason,
+        )
+    except Exception as exc:
+        result.core_error = f"{type(exc).__name__}: {exc}"
+        if raise_core_errors:
+            raise
+        return result
+
+    if core_snapshot is None:
+        return result
+
+    await apply_snapshot(core_snapshot)
+    result.core_applied = True
+    result.core_config_count = len(getattr(core_snapshot, "configs", []) or [])
+    result.core_generation = getattr(core_snapshot, "generation", None)
+    return result
+
+
 def reconcile_config_ids(
     *,
     active_ids: list[str],

piphi_runtime_kit_python-0.4.5/tests/test_config_sync.py

@@ -0,0 +1,332 @@
+import pytest
+import httpx
+
+from piphi_runtime_kit_python import (
+    ConfigSyncCoordinator,
+    RuntimeConfig,
+    RuntimeConfigRehydrateResult,
+    RuntimeContext,
+    RuntimeConfigSnapshot,
+    RuntimeProcessState,
+    build_runtime_config_snapshot_from_core_rows,
+    fetch_core_runtime_config_snapshot,
+    load_runtime_config_snapshot,
+    reconcile_config_ids,
+    rehydrate_runtime_configs,
+    resolve_core_base_url,
+    resolve_runtime_config_snapshot_path,
+)
+
+
+class _CoreConfigResponse:
+    def __init__(self, payload):
+        self.payload = payload
+
+    def raise_for_status(self) -> None:
+        return None
+
+    def json(self):
+        return self.payload
+
+
+class _CoreConfigClient:
+    def __init__(self, payload):
+        self.payload = payload
+        self.requests: list[dict] = []
+
+    async def get(self, url: str, **kwargs):
+        self.requests.append({"url": url, **kwargs})
+        return _CoreConfigResponse(self.payload)
+
+
+class _OfflineCoreClient:
+    async def get(self, *_args, **_kwargs):
+        raise httpx.ConnectError("All connection attempts failed")
+
+
+def test_reconcile_config_ids_returns_removed_and_unchanged_ids() -> None:
+    removed_ids, unchanged_ids = reconcile_config_ids(
+        active_ids=["a", "b", "c"],
+        incoming_ids=["b", "c", "d"],
+    )
+
+    assert removed_ids == ["a"]
+    assert unchanged_ids == ["b", "c"]
+
+
+def test_config_sync_coordinator_detects_stale_snapshot() -> None:
+    state = RuntimeProcessState(current_generation=10)
+    coordinator = ConfigSyncCoordinator(process_state=state)
+    snapshot = RuntimeConfigSnapshot(
+        container_id="container-1",
+        generation=9,
+        configs=[RuntimeConfig(id="device-1")],
+    )
+
+    assert coordinator.is_stale(snapshot) is True
+
+
+def test_config_sync_coordinator_updates_generation() -> None:
+    state = RuntimeProcessState()
+    coordinator = ConfigSyncCoordinator(process_state=state)
+
+    assert coordinator.mark_generation(42) == 42
+    assert state.current_generation == 42
+
+
+def test_resolve_core_base_url_uses_managed_runtime_env(monkeypatch) -> None:
+    monkeypatch.setenv("PIPHI_CORE_BASE_URL", "http://127.0.0.1:31419/")
+
+    assert resolve_core_base_url() == "http://127.0.0.1:31419"
+
+
+def test_resolve_runtime_config_snapshot_path_uses_container_id(monkeypatch, tmp_path) -> None:
+    monkeypatch.delenv("PIPHI_CONFIG_SNAPSHOT_PATH", raising=False)
+    monkeypatch.setenv("PIPHI_CONTAINER_ID", "container-1")
+
+    assert resolve_runtime_config_snapshot_path(volume_dir=tmp_path) == tmp_path / "container-1.json"
+
+
+def test_resolve_runtime_config_snapshot_path_prefers_explicit_path(monkeypatch, tmp_path) -> None:
+    explicit_path = tmp_path / "custom.json"
+    monkeypatch.setenv("PIPHI_CONFIG_SNAPSHOT_PATH", str(explicit_path))
+
+    assert resolve_runtime_config_snapshot_path(volume_dir=tmp_path) == explicit_path
+
+
+def test_load_runtime_config_snapshot_reads_core_volume_contract(tmp_path) -> None:
+    snapshot_path = tmp_path / "container-1.json"
+    snapshot_path.write_text(
+        """
+        {
+          "schema_version": 1,
+          "container_id": "container-1",
+          "integration_id": "integration-1",
+          "reason": "startup",
+          "generation": 42,
+          "updated_at": "2026-04-27T12:00:00+00:00",
+          "configs": [{"id": "device-1", "serial": "abc123"}],
+          "deleted_config_ids": ["device-2"],
+          "config_hash": "sha256:abc",
+          "internal_token": "runtime-token"
+        }
+        """,
+        encoding="utf-8",
+    )
+
+    snapshot = load_runtime_config_snapshot(path=snapshot_path)
+
+    assert snapshot is not None
+    assert snapshot.schema_version == 1
+    assert snapshot.container_id == "container-1"
+    assert snapshot.generation == 42
+    assert snapshot.configs[0].id == "device-1"
+    assert snapshot.deleted_config_ids == ["device-2"]
+    assert snapshot.config_hash == "sha256:abc"
+    assert snapshot.internal_token == "runtime-token"
+
+
+def test_load_runtime_config_snapshot_returns_none_for_missing_or_invalid_snapshot(tmp_path) -> None:
+    assert load_runtime_config_snapshot(path=tmp_path / "missing.json") is None
+
+    invalid_path = tmp_path / "invalid.json"
+    invalid_path.write_text("not-json", encoding="utf-8")
+
+    assert load_runtime_config_snapshot(path=invalid_path) is None
+
+
+def test_build_runtime_config_snapshot_from_core_rows_ignores_invalid_rows() -> None:
+    snapshot = build_runtime_config_snapshot_from_core_rows(
+        [
+            {"config_data": {"id": "device-1", "name": "Kitchen"}},
+            {"config_data": None},
+            {"not_config_data": {"id": "device-2"}},
+        ],
+        container_id="container-1",
+    )
+
+    assert snapshot.container_id == "container-1"
+    assert snapshot.reason == "startup_rehydrate"
+    assert len(snapshot.configs) == 1
+    assert snapshot.configs[0].id == "device-1"
+    assert snapshot.configs[0].container_id == "container-1"
+
+
+@pytest.mark.asyncio
+async def test_fetch_core_runtime_config_snapshot_uses_runtime_auth_headers() -> None:
+    runtime_context = RuntimeContext()
+    runtime_context.auth.update(
+        container_id="container-1",
+        internal_token="secret-token",
+    )
+    client = _CoreConfigClient(
+        [{"config_data": {"id": "device-1", "name": "Kitchen"}}]
+    )
+
+    snapshot = await fetch_core_runtime_config_snapshot(
+        runtime_context=runtime_context,
+        client=client,
+        core_base_url="http://core.local",
+    )
+
+    assert snapshot is not None
+    assert snapshot.configs[0].id == "device-1"
+    assert client.requests[0]["url"] == (
+        "http://core.local/api/v2/integrations/config/fetch/all/by/container/internal"
+    )
+    assert client.requests[0]["params"] == {"container_id": "container-1"}
+    assert client.requests[0]["headers"]["X-Container-Id"] == "container-1"
+    assert client.requests[0]["headers"]["X-PiPhi-Integration-Token"] == "secret-token"
+
+
+@pytest.mark.asyncio
+async def test_rehydrate_runtime_configs_applies_snapshot_then_core(tmp_path) -> None:
+    runtime_context = RuntimeContext()
+    runtime_context.auth.update(
+        container_id="container-1",
+        internal_token="secret-token",
+    )
+    snapshot_path = tmp_path / "container-1.json"
+    snapshot_path.write_text(
+        """
+        {
+          "schema_version": 1,
+          "container_id": "container-1",
+          "reason": "startup_snapshot",
+          "generation": 1,
+          "configs": [{"id": "snapshot-device", "name": "Snapshot"}]
+        }
+        """,
+        encoding="utf-8",
+    )
+    applied_sources: list[tuple[str | None, list[str]]] = []
+
+    async def apply_snapshot(snapshot: RuntimeConfigSnapshot) -> None:
+        applied_sources.append((snapshot.reason, [config.id for config in snapshot.configs]))
+
+    result = await rehydrate_runtime_configs(
+        runtime_context=runtime_context,
+        client=_CoreConfigClient(
+            [{"config_data": {"id": "core-device", "name": "Core"}}]
+        ),
+        apply_snapshot=apply_snapshot,
+        core_base_url="http://core.local",
+        snapshot_path=snapshot_path,
+    )
+
+    assert isinstance(result, RuntimeConfigRehydrateResult)
+    assert result.snapshot_applied is True
+    assert result.core_applied is True
+    assert result.snapshot_config_count == 1
+    assert result.core_config_count == 1
+    assert applied_sources == [
+        ("startup_snapshot", ["snapshot-device"]),
+        ("startup_rehydrate", ["core-device"]),
+    ]
+
+
+@pytest.mark.asyncio
+async def test_rehydrate_runtime_configs_keeps_snapshot_when_core_is_offline(tmp_path) -> None:
+    runtime_context = RuntimeContext()
+    runtime_context.auth.update(
+        container_id="container-1",
+        internal_token="secret-token",
+    )
+    snapshot_path = tmp_path / "container-1.json"
+    snapshot_path.write_text(
+        """
+        {
+          "schema_version": 1,
+          "container_id": "container-1",
+          "generation": 2,
+          "configs": [{"id": "snapshot-device", "name": "Snapshot"}]
+        }
+        """,
+        encoding="utf-8",
+    )
+    applied_ids: list[str] = []
+
+    async def apply_snapshot(snapshot: RuntimeConfigSnapshot) -> None:
+        applied_ids.extend(config.id for config in snapshot.configs)
+
+    result = await rehydrate_runtime_configs(
+        runtime_context=runtime_context,
+        client=_OfflineCoreClient(),
+        apply_snapshot=apply_snapshot,
+        snapshot_path=snapshot_path,
+    )
+
+    assert result.snapshot_applied is True
+    assert result.core_attempted is True
+    assert result.core_applied is False
+    assert result.core_error is not None
+    assert applied_ids == ["snapshot-device"]
+
+
+@pytest.mark.asyncio
+async def test_rehydrate_runtime_configs_skips_core_without_auth(tmp_path) -> None:
+    runtime_context = RuntimeContext()
+    snapshot_path = tmp_path / "container-1.json"
+    snapshot_path.write_text(
+        """
+        {
+          "schema_version": 1,
+          "container_id": "container-1",
+          "configs": [{"id": "snapshot-device", "name": "Snapshot"}]
+        }
+        """,
+        encoding="utf-8",
+    )
+    applied_ids: list[str] = []
+
+    async def apply_snapshot(snapshot: RuntimeConfigSnapshot) -> None:
+        applied_ids.extend(config.id for config in snapshot.configs)
+
+    result = await rehydrate_runtime_configs(
+        runtime_context=runtime_context,
+        client=_CoreConfigClient(
+            [{"config_data": {"id": "core-device", "name": "Core"}}]
+        ),
+        apply_snapshot=apply_snapshot,
+        snapshot_path=snapshot_path,
+    )
+
+    assert result.snapshot_applied is True
+    assert result.core_attempted is False
+    assert result.missing_runtime_auth is True
+    assert applied_ids == ["snapshot-device"]
+
+
+@pytest.mark.asyncio
+async def test_config_sync_coordinator_apply_snapshot_orchestrates_callbacks() -> None:
+    state = RuntimeProcessState(current_generation=1)
+    coordinator = ConfigSyncCoordinator(process_state=state)
+    snapshot = RuntimeConfigSnapshot(
+        container_id="container-1",
+        generation=2,
+        configs=[RuntimeConfig(id="device-2"), RuntimeConfig(id="device-3")],
+    )
+    active_ids = ["device-1", "device-2"]
+    applied: list[str] = []
+    removed: list[str] = []
+
+    async def apply_config(config: RuntimeConfig) -> None:
+        applied.append(config.id)
+
+    async def remove_config(config_id: str) -> bool:
+        removed.append(config_id)
+        return True
+
+    response = await coordinator.apply_snapshot(
+        snapshot=snapshot,
+        active_config_ids=active_ids,
+        apply_config=apply_config,
+        remove_config=remove_config,
+        get_active_config_ids=lambda: ["device-2", "device-3"],
+    )
+
+    assert applied == ["device-2", "device-3"]
+    assert removed == ["device-1"]
+    assert response.status == "synced"
+    assert response.generation == 2
+    assert response.active_config_ids == ["device-2", "device-3"]

piphi_runtime_kit_python-0.4.3/tests/test_config_sync.py

@@ -1,138 +0,0 @@
-import pytest
-
-from piphi_runtime_kit_python import (
-    ConfigSyncCoordinator,
-    RuntimeConfig,
-    RuntimeConfigSnapshot,
-    RuntimeProcessState,
-    load_runtime_config_snapshot,
-    reconcile_config_ids,
-    resolve_core_base_url,
-    resolve_runtime_config_snapshot_path,
-)
-
-
-def test_reconcile_config_ids_returns_removed_and_unchanged_ids() -> None:
-    removed_ids, unchanged_ids = reconcile_config_ids(
-        active_ids=["a", "b", "c"],
-        incoming_ids=["b", "c", "d"],
-    )
-
-    assert removed_ids == ["a"]
-    assert unchanged_ids == ["b", "c"]
-
-
-def test_config_sync_coordinator_detects_stale_snapshot() -> None:
-    state = RuntimeProcessState(current_generation=10)
-    coordinator = ConfigSyncCoordinator(process_state=state)
-    snapshot = RuntimeConfigSnapshot(
-        container_id="container-1",
-        generation=9,
-        configs=[RuntimeConfig(id="device-1")],
-    )
-
-    assert coordinator.is_stale(snapshot) is True
-
-
-def test_config_sync_coordinator_updates_generation() -> None:
-    state = RuntimeProcessState()
-    coordinator = ConfigSyncCoordinator(process_state=state)
-
-    assert coordinator.mark_generation(42) == 42
-    assert state.current_generation == 42
-
-
-def test_resolve_core_base_url_uses_managed_runtime_env(monkeypatch) -> None:
-    monkeypatch.setenv("PIPHI_CORE_BASE_URL", "http://127.0.0.1:31419/")
-
-    assert resolve_core_base_url() == "http://127.0.0.1:31419"
-
-
-def test_resolve_runtime_config_snapshot_path_uses_container_id(monkeypatch, tmp_path) -> None:
-    monkeypatch.delenv("PIPHI_CONFIG_SNAPSHOT_PATH", raising=False)
-    monkeypatch.setenv("PIPHI_CONTAINER_ID", "container-1")
-
-    assert resolve_runtime_config_snapshot_path(volume_dir=tmp_path) == tmp_path / "container-1.json"
-
-
-def test_resolve_runtime_config_snapshot_path_prefers_explicit_path(monkeypatch, tmp_path) -> None:
-    explicit_path = tmp_path / "custom.json"
-    monkeypatch.setenv("PIPHI_CONFIG_SNAPSHOT_PATH", str(explicit_path))
-
-    assert resolve_runtime_config_snapshot_path(volume_dir=tmp_path) == explicit_path
-
-
-def test_load_runtime_config_snapshot_reads_core_volume_contract(tmp_path) -> None:
-    snapshot_path = tmp_path / "container-1.json"
-    snapshot_path.write_text(
-        """
-        {
-          "schema_version": 1,
-          "container_id": "container-1",
-          "integration_id": "integration-1",
-          "reason": "startup",
-          "generation": 42,
-          "updated_at": "2026-04-27T12:00:00+00:00",
-          "configs": [{"id": "device-1", "serial": "abc123"}],
-          "deleted_config_ids": ["device-2"],
-          "config_hash": "sha256:abc",
-          "internal_token": "runtime-token"
-        }
-        """,
-        encoding="utf-8",
-    )
-
-    snapshot = load_runtime_config_snapshot(path=snapshot_path)
-
-    assert snapshot is not None
-    assert snapshot.schema_version == 1
-    assert snapshot.container_id == "container-1"
-    assert snapshot.generation == 42
-    assert snapshot.configs[0].id == "device-1"
-    assert snapshot.deleted_config_ids == ["device-2"]
-    assert snapshot.config_hash == "sha256:abc"
-    assert snapshot.internal_token == "runtime-token"
-
-
-def test_load_runtime_config_snapshot_returns_none_for_missing_or_invalid_snapshot(tmp_path) -> None:
-    assert load_runtime_config_snapshot(path=tmp_path / "missing.json") is None
-
-    invalid_path = tmp_path / "invalid.json"
-    invalid_path.write_text("not-json", encoding="utf-8")
-
-    assert load_runtime_config_snapshot(path=invalid_path) is None
-
-
-@pytest.mark.asyncio
-async def test_config_sync_coordinator_apply_snapshot_orchestrates_callbacks() -> None:
-    state = RuntimeProcessState(current_generation=1)
-    coordinator = ConfigSyncCoordinator(process_state=state)
-    snapshot = RuntimeConfigSnapshot(
-        container_id="container-1",
-        generation=2,
-        configs=[RuntimeConfig(id="device-2"), RuntimeConfig(id="device-3")],
-    )
-    active_ids = ["device-1", "device-2"]
-    applied: list[str] = []
-    removed: list[str] = []
-
-    async def apply_config(config: RuntimeConfig) -> None:
-        applied.append(config.id)
-
-    async def remove_config(config_id: str) -> bool:
-        removed.append(config_id)
-        return True
-
-    response = await coordinator.apply_snapshot(
-        snapshot=snapshot,
-        active_config_ids=active_ids,
-        apply_config=apply_config,
-        remove_config=remove_config,
-        get_active_config_ids=lambda: ["device-2", "device-3"],
-    )
-
-    assert applied == ["device-2", "device-3"]
-    assert removed == ["device-1"]
-    assert response.status == "synced"
-    assert response.generation == 2
-    assert response.active_config_ids == ["device-2", "device-3"]