feat(guard): sync White Rabbit edge events

Adds White Rabbit Guard v1 edge event envelopes, local queue persistence, v1 event upload during normal sync/connect flows, resilient fallback when the v1 endpoint is unavailable, and terminal rejection handling so queued events cannot starve newer sync work.

Author: kantorcodes

src/codex_plugin_scanner/guard/cli/connect_flow.py

@@ -107,36 +107,37 @@ def run_guard_connect_command(
         sync_payload = sync_receipts(store)
     except GuardSyncNotAvailableError as plan_error:
         plan_msg = str(plan_error).strip() or "Cloud sync requires a paid Guard plan."
+        pending_sync_payload = dict(runtime_sync_summary)
+        pending_sync_payload["synced_at"] = None
         pending_state = _record_connect_result(
             daemon_client=daemon_client,
             store=store,
             request_id=str(connect_request["request_id"]),
-            status="connected",
-            milestone="sync_not_available",
+            status="retry_required",
+            milestone="first_sync_failed",
             reason=plan_msg,
+            sync=pending_sync_payload,
         )
         return build_connect_payload(
             state=pending_state,
             browser_opened=browser_opened,
             connect_url=browser_url,
             sync_url=sync_url,
-            connected=True,
+            connected=False,
+            sync=pending_sync_payload,
             sync_available=False,
             sync_message=plan_msg,
         )
     except (RuntimeError, OSError, urllib.error.URLError, json.JSONDecodeError) as error:
         sync_message = str(error)
-        if runtime_sync_error and not _is_paid_plan_sync_error(sync_message):
-            sync_message = runtime_sync_error
-        sync_is_plan_limited = _is_paid_plan_sync_error(sync_message)
         pending_sync_payload = dict(runtime_sync_summary)
         pending_sync_payload["synced_at"] = None
         pending_state = _record_connect_result(
             daemon_client=daemon_client,
             store=store,
             request_id=str(connect_request["request_id"]),
-            status="connected",
-            milestone="first_sync_pending",
+            status="retry_required",
+            milestone="first_sync_failed",
             reason=sync_message,
             sync=pending_sync_payload,
         )
@@ -145,10 +146,9 @@ def run_guard_connect_command(
             browser_opened=browser_opened,
             connect_url=browser_url,
             sync_url=sync_url,
-            connected=True,
+            connected=False,
             sync=pending_sync_payload,
             sync_message=sync_message,
-            sync_available=False if sync_is_plan_limited else None,
         )
     sync_payload["runtime_session_synced_at"] = runtime_sync_summary["runtime_session_synced_at"]
     sync_payload["runtime_session_id"] = runtime_sync_summary["runtime_session_id"]

src/codex_plugin_scanner/guard/edge_events.py

@@ -0,0 +1,88 @@
+"""Builders for Guard Cloud v1 events emitted by the local edge runtime."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import cast
+
+from .models import GuardReceipt
+from .schemas.guard_event_v1 import GuardEventType, GuardEventV1
+
+
+def build_receipt_event(
+    receipt: GuardReceipt,
+    *,
+    device_id: str | None = None,
+    workspace_id: str | None = None,
+) -> GuardEventV1:
+    payload: dict[str, object] = {
+        "receiptId": receipt.receipt_id,
+        "harness": receipt.harness,
+        "artifactId": receipt.artifact_id,
+        "artifactHash": receipt.artifact_hash,
+        "artifactName": receipt.artifact_name,
+        "sourceScope": receipt.source_scope,
+        "policyDecision": receipt.policy_decision,
+        "capabilitiesSummary": receipt.capabilities_summary,
+        "changedCapabilities": list(receipt.changed_capabilities),
+        "provenanceSummary": receipt.provenance_summary,
+        "userOverride": receipt.user_override,
+    }
+    event_id = f"guard-event-{_fingerprint('receipt.created', receipt.receipt_id)[:32]}"
+    return GuardEventV1(
+        event_id=event_id,
+        idempotency_key=f"receipt.created:{receipt.receipt_id}",
+        event_type="receipt.created",
+        source="edge",
+        occurred_at=receipt.timestamp,
+        workspace_id=workspace_id,
+        device_id=device_id,
+        payload=payload,
+    )
+
+
+def build_approval_event(
+    *,
+    request_id: str,
+    event_type: str,
+    occurred_at: str,
+    payload: dict[str, object],
+    device_id: str | None = None,
+    workspace_id: str | None = None,
+) -> GuardEventV1:
+    if event_type not in {"approval.created", "approval.resolved"}:
+        raise ValueError("Approval event type must be approval.created or approval.resolved")
+    return GuardEventV1(
+        event_id=f"guard-event-{_fingerprint(event_type, request_id, occurred_at)[:32]}",
+        idempotency_key=f"{event_type}:{request_id}:{occurred_at}",
+        event_type=cast(GuardEventType, event_type),
+        source="approval-center",
+        occurred_at=occurred_at,
+        workspace_id=workspace_id,
+        device_id=device_id,
+        payload=payload,
+    )
+
+
+def build_policy_event(
+    *,
+    policy_key: str,
+    occurred_at: str,
+    payload: dict[str, object],
+    device_id: str | None = None,
+    workspace_id: str | None = None,
+) -> GuardEventV1:
+    return GuardEventV1(
+        event_id=f"guard-event-{_fingerprint('policy.changed', policy_key, occurred_at)[:32]}",
+        idempotency_key=f"policy.changed:{policy_key}:{occurred_at}",
+        event_type="policy.changed",
+        source="policy",
+        occurred_at=occurred_at,
+        workspace_id=workspace_id,
+        device_id=device_id,
+        payload=payload,
+    )
+
+
+def _fingerprint(*parts: str) -> str:
+    return hashlib.sha256(":".join(parts).encode()).hexdigest()

src/codex_plugin_scanner/guard/runtime/__init__.py

@@ -4,6 +4,7 @@
     GuardSyncNotAvailableError,
     GuardSyncNotConfiguredError,
     guard_run,
+    sync_guard_events,
     sync_receipts,
     sync_runtime_session,
 )
@@ -12,6 +13,7 @@
     "GuardSyncNotAvailableError",
     "GuardSyncNotConfiguredError",
     "guard_run",
+    "sync_guard_events",
     "sync_receipts",
     "sync_runtime_session",
 ]

src/codex_plugin_scanner/guard/runtime/runner.py

@@ -480,10 +480,69 @@ def sync_receipts(store: GuardStore) -> dict[str, object]:
         "inventory": 0,
         "inventory_tracked": len(inventory),
     }
+    summary["guard_events_v1"] = sync_guard_events(store)
     store.set_sync_payload("sync_summary", summary, now)
     return summary
 
 
+def sync_guard_events(store: GuardStore) -> dict[str, object]:
+    """Push pending GuardEventV1 envelopes to Guard Cloud."""
+
+    credentials = store.get_sync_credentials()
+    if credentials is None:
+        raise GuardSyncNotConfiguredError("Guard is not logged in.")
+    sync_url = _guard_events_sync_url(str(credentials["sync_url"]))
+    total_events = 0
+    total_accepted = 0
+    synced_at = _now()
+    while True:
+        pending_events = store.list_guard_events_v1(uploaded=False, limit=200)
+        if not pending_events:
+            break
+        body = json.dumps({"events": [event["payload"] for event in pending_events]}).encode("utf-8")
+        request = urllib.request.Request(
+            sync_url,
+            data=body,
+            method="POST",
+            headers=_guard_sync_headers(str(credentials["token"])),
+        )
+        try:
+            payload = _urlopen_json_with_timeout_retry(
+                request=request,
+                timeout_seconds=_SYNC_HTTP_TIMEOUT_SECONDS,
+                retry_timeout_seconds=_SYNC_HTTP_RETRY_TIMEOUT_SECONDS,
+            )
+        except urllib.error.HTTPError as error:
+            if error.code == 404:
+                summary = {
+                    "synced_at": synced_at,
+                    "events": total_events,
+                    "accepted": total_accepted,
+                    "sync_skipped": True,
+                    "sync_reason": "guard_events_endpoint_unavailable",
+                }
+                store.set_sync_payload("guard_events_v1_summary", summary, synced_at)
+                return summary
+            if error.code == 403:
+                is_plan, message = _check_plan_restriction_403(error)
+                if is_plan:
+                    raise GuardSyncNotAvailableError(message) from error
+                raise RuntimeError(message) from error
+            raise RuntimeError(_sync_http_error_message(error)) from error
+        except OSError as error:
+            raise RuntimeError(_sync_url_error_message(error)) from error
+        completed_ids = _completed_guard_event_ids(payload)
+        synced_at = _sync_timestamp(payload)
+        uploaded = store.mark_guard_events_v1_uploaded(completed_ids, synced_at)
+        total_events += len(pending_events)
+        total_accepted += uploaded
+        if uploaded == 0 or len(pending_events) < 200:
+            break
+    summary = {"synced_at": synced_at, "events": total_events, "accepted": total_accepted}
+    store.set_sync_payload("guard_events_v1_summary", summary, synced_at)
+    return summary
+
+
 def sync_runtime_session(
     store: GuardStore,
     *,
@@ -951,6 +1010,45 @@ def _normalized_runtime_sessions_sync_url(sync_url: str) -> str:
     )
 
 
+def _guard_events_sync_url(sync_url: str) -> str:
+    parsed = urllib.parse.urlsplit(_normalized_receipts_sync_url(sync_url))
+    if parsed.path.rstrip("/").endswith("/api/v1/guard/events"):
+        return urllib.parse.urlunsplit((parsed.scheme, parsed.netloc, parsed.path.rstrip("/"), parsed.query, ""))
+    path = parsed.path.rstrip("/")
+    for suffix in (
+        "/api/guard/receipts/sync",
+        "/guard/receipts/sync",
+        "/registry/api/v1/guard/receipts/sync",
+    ):
+        if path.endswith(suffix):
+            path = path[: -len(suffix)]
+            break
+    return urllib.parse.urlunsplit(
+        (
+            parsed.scheme,
+            parsed.netloc,
+            path.rstrip("/") + "/api/v1/guard/events",
+            parsed.query,
+            "",
+        )
+    )
+
+
+def _completed_guard_event_ids(payload: dict[str, object]) -> list[str]:
+    statuses = payload.get("statuses")
+    if not isinstance(statuses, list):
+        return []
+    completed: list[str] = []
+    for item in statuses:
+        if not isinstance(item, dict):
+            continue
+        status = str(item.get("status") or "")
+        event_id = item.get("eventId")
+        if status in {"accepted", "duplicate", "rejected"} and isinstance(event_id, str):
+            completed.append(event_id)
+    return completed
+
+
 def _cloud_sync_receipts_payload(store: GuardStore, receipts: list[dict[str, object]]) -> list[dict[str, object]]:
     device_id, device_name = _guard_device_metadata(store)
     return [_cloud_sync_receipt_payload(receipt, device_id=device_id, device_name=device_name) for receipt in receipts]

src/codex_plugin_scanner/guard/schemas/guard_event_v1.py

@@ -0,0 +1,74 @@
+"""Guard Cloud event schema shared by the edge runtime and v1 ingest API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, cast
+
+GuardEventSource = Literal["edge", "approval-center", "policy", "protect-api"]
+GuardEventType = Literal["receipt.created", "approval.created", "approval.resolved", "policy.changed"]
+
+
+@dataclass(frozen=True, slots=True)
+class GuardEventV1:
+    """Versioned event envelope for replay-safe Guard Cloud sync."""
+
+    event_id: str
+    idempotency_key: str
+    event_type: GuardEventType
+    source: GuardEventSource
+    occurred_at: str
+    workspace_id: str | None = None
+    device_id: str | None = None
+    payload: dict[str, object] = field(default_factory=dict)
+    schema_version: str = "guard.event.v1"
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "schemaVersion": self.schema_version,
+            "eventId": self.event_id,
+            "idempotencyKey": self.idempotency_key,
+            "eventType": self.event_type,
+            "source": self.source,
+            "occurredAt": self.occurred_at,
+            "workspaceId": self.workspace_id,
+            "deviceId": self.device_id,
+            "payload": self.payload,
+        }
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, object]) -> GuardEventV1:
+        schema_version = str(payload.get("schemaVersion") or "")
+        if schema_version != "guard.event.v1":
+            raise ValueError("Guard event schemaVersion must be guard.event.v1")
+        event_id = _required_string(payload, "eventId")
+        idempotency_key = _required_string(payload, "idempotencyKey")
+        event_type = _required_string(payload, "eventType")
+        source = _required_string(payload, "source")
+        occurred_at = _required_string(payload, "occurredAt")
+        event_payload = payload.get("payload")
+        if not isinstance(event_payload, dict):
+            raise ValueError("Guard event payload must be an object")
+        if event_type not in {"receipt.created", "approval.created", "approval.resolved", "policy.changed"}:
+            raise ValueError(f"Unsupported Guard event type: {event_type}")
+        if source not in {"edge", "approval-center", "policy", "protect-api"}:
+            raise ValueError(f"Unsupported Guard event source: {source}")
+        workspace_id = payload.get("workspaceId")
+        device_id = payload.get("deviceId")
+        return cls(
+            event_id=event_id,
+            idempotency_key=idempotency_key,
+            event_type=cast(GuardEventType, event_type),
+            source=cast(GuardEventSource, source),
+            occurred_at=occurred_at,
+            workspace_id=workspace_id if isinstance(workspace_id, str) else None,
+            device_id=device_id if isinstance(device_id, str) else None,
+            payload={str(key): value for key, value in event_payload.items()},
+        )
+
+
+def _required_string(payload: dict[str, object], key: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"Guard event {key} must be a non-empty string")
+    return value