plugin-scanner 2.0.666__tar.gz → 2.0.668__tar.gz

{plugin_scanner-2.0.666 → plugin_scanner-2.0.668}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.666
+Version: 2.0.668
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://github.com/hashgraph-online/hol-guard
 Project-URL: Repository, https://github.com/hashgraph-online/hol-guard

{plugin_scanner-2.0.666 → plugin_scanner-2.0.668}/dashboard/src/guard-api.ts

@@ -33,6 +33,7 @@ import type {
   GuardManagedInstall,
   GuardNotificationSetupResult,
   GuardPolicyDecision,
+  GuardCloudException,
   PackageManagerProtection,
   CodexResumeStatus,
   GuardCodexResumeResult,
@@ -1577,6 +1578,16 @@ export async function fetchPolicy(harness: string): Promise<GuardPolicyDecision[
   return payload.items;
 }
 
+
+export async function fetchCloudExceptions(harness?: string): Promise<GuardCloudException[]> {
+  if (isGuardDemoMode()) {
+    return [];
+  }
+  const query = harness ? `?harness=${encodeURIComponent(harness)}` : "";
+  const payload = await readJson<{ items: GuardCloudException[] }>(`/v1/policy/cloud-exceptions${query}`);
+  return payload.items;
+}
+
 export async function fetchPolicies(): Promise<GuardPolicyDecision[]> {
   if (isGuardDemoMode()) {
     return getDemoPolicy("codex");

{plugin_scanner-2.0.666 → plugin_scanner-2.0.668}/dashboard/src/guard-types.ts

@@ -482,6 +482,37 @@ export type GuardPolicyDecision = {
   updated_at: string;
 };
 
+export const GUARD_CLOUD_EXCEPTION_ACK_STATUSES = [
+  "pending",
+  "synced",
+  "failed",
+  "offline",
+] as const;
+
+export type GuardCloudExceptionAckStatus = (typeof GUARD_CLOUD_EXCEPTION_ACK_STATUSES)[number];
+
+export const GUARD_CLOUD_EXCEPTION_EFFECTS = ["allow"] as const;
+
+export type GuardCloudExceptionEffect = (typeof GUARD_CLOUD_EXCEPTION_EFFECTS)[number];
+
+export type GuardCloudExceptionScope = DecisionScope | "global";
+
+export type GuardCloudException = {
+  id: string;
+  effect: GuardCloudExceptionEffect;
+  scope: GuardCloudExceptionScope;
+  harness: string | null;
+  owner: string;
+  approver: string | null;
+  expiry: string;
+  source_receipt_id: string | null;
+  bundle_hash: string | null;
+  ack_status: GuardCloudExceptionAckStatus | null;
+  last_used_at: string | null;
+  rejection_reason: string | null;
+};
+
+
 export type GuardManagedInstall = {
   harness: string;
   active: boolean;

{plugin_scanner-2.0.666 → plugin_scanner-2.0.668}/dashboard/src/policy-cloud-exceptions-boundary.test.ts

@@ -119,6 +119,7 @@ assert(guardApiSource.includes("fetchPolicies"), "guard-api must expose fetchPol
 assert(guardApiSource.includes("savePolicyDecision"), "guard-api must expose savePolicyDecision baseline");
 assert(guardApiSource.includes("clearPolicy"), "guard-api must expose clearPolicy");
 assert(guardApiSource.includes("/v1/policy"), "guard-api must call /v1/policy endpoints");
+assert(guardApiSource.includes("fetchCloudExceptions"), "guard-api must expose fetchCloudExceptions");
 
 assert(boundaryDoc.includes("Remembered rules"), "boundary doc must define Remembered rules");
 assert(boundaryDoc.includes("Cloud exceptions"), "boundary doc must define Cloud exceptions");

{plugin_scanner-2.0.666 → plugin_scanner-2.0.668}/docs/guard/policy-cloud-exceptions-boundary.md

@@ -43,9 +43,10 @@ Local Policy must **not** author broad local exceptions directly.
 
 | Endpoint / module | Role today |
 | --- | --- |
-| `GET /v1/policy` | Lists local `GuardPolicyDecision` rows |
+| `GET /v1/policy` | Lists local `GuardPolicyDecision` rows plus `cloud_exceptions` DTO field |
 | `POST /v1/policy/decisions` | Saves local policy decision (used by exception form today) |
 | `POST /v1/policy/clear` | Clears local remembered rules |
+| `GET /v1/policy/cloud-exceptions` | Lists active Cloud exception DTO rows |
 | `POST /v1/policy/sync` | Syncs Cloud policy bundle |
 | `policy_bundle_parser.py` | Schema validation, bundle hash, payload hash, RSA signature verify |
 | `policy_bundle_trusted_keys.py` | Trusted signing keys, key expiry |
@@ -174,4 +175,5 @@ Do not rewrite Review/Inbox components to implement Policy features.
 ## Phase 0 completion
 
 Phase 0 delivers this boundary doc, audit notes, and automated boundary tests.
-Implementation begins in Phase 1 (IA rename, remove local exception authoring).
+Phase 3 adds the local Cloud exception DTO (`cloud_exceptions.py`), separate sync
+storage, and `/v1/policy` + `/v1/policy/cloud-exceptions` API fields.

{plugin_scanner-2.0.666 → plugin_scanner-2.0.668}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.0.666"
+version = "2.0.668"
 description = "Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.666 → plugin_scanner-2.0.668}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.666"
+version = "2.0.668"
 description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, and OpenCode."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.666 → plugin_scanner-2.0.668}/src/codex_plugin_scanner/guard/aibom_cli.py

@@ -13,6 +13,7 @@ from typing import Literal
 
 from .adapters.base import HarnessContext
 from .consumer import detect_all
+from .inventory_cisco import run_cisco_inventory_scans
 from .inventory_contract import (
     GuardAgentInventorySnapshot,
     extract_aibom_metadata_extensions,
@@ -29,6 +30,16 @@ AibomExportFormat = Literal["json", "markdown"]
 class AibomCliOptions:
     include_symlinks: bool = True
     follow_unsafe_symlinks: bool = False
+    cisco_skill_scan: str = "off"
+    cisco_mcp_scan: str = "off"
+    cisco_timeout_seconds: float | None = None
+
+
+_AIBOM_CLOUD_SYNC_OPTIONS = AibomCliOptions(
+    cisco_skill_scan="auto",
+    cisco_mcp_scan="auto",
+    cisco_timeout_seconds=30.0,
+)
 
 
 def collect_aibom_snapshots(
@@ -42,12 +53,21 @@ def collect_aibom_snapshots(
     for detection in detect_all(context):
         if not detection.installed and not detection.artifacts:
             continue
+        cisco_runs = run_cisco_inventory_scans(
+            harness=str(getattr(detection, "harness", "unknown")),
+            context=context,
+            detection=detection,
+            mcp_mode=resolved.cisco_mcp_scan,
+            skill_mode=resolved.cisco_skill_scan,
+            timeout_seconds=resolved.cisco_timeout_seconds,
+        )
         snapshots.append(
             inventory_snapshot_from_detection(
                 detection,
                 generated_at=generated_at,
                 home_dir=context.home_dir,
                 workspace_dir=context.workspace_dir,
+                cisco_runs=cisco_runs,
                 include_symlinks=resolved.include_symlinks,
                 follow_unsafe_symlinks=resolved.follow_unsafe_symlinks,
             )
@@ -279,7 +299,12 @@ def sync_aibom_snapshots(
     if workspace_id is None:
         raise GuardSyncNotConfiguredError("Guard Cloud workspace is not configured. Run `hol-guard connect` first.")
 
-    snapshots = collect_aibom_snapshots(context, generated_at=generated_at, options=options)
+    resolved_options = options or _AIBOM_CLOUD_SYNC_OPTIONS
+    snapshots = collect_aibom_snapshots(
+        context,
+        generated_at=generated_at,
+        options=resolved_options,
+    )
     if not snapshots:
         synced_at = generated_at
         summary = {

{plugin_scanner-2.0.666 → plugin_scanner-2.0.668}/src/codex_plugin_scanner/guard/aibom_trust_metadata.py

@@ -8,7 +8,7 @@ from pathlib import Path
 from typing import Literal
 
 from ..checks.skill_security import resolve_skill_security_context
-from ..models import ScanOptions
+from ..models import ScanOptions, Severity
 from ..trust_instruction_scoring import build_instruction_domain
 from ..trust_mcp_scoring import build_mcp_domain, build_mcp_surface_domain
 from ..trust_models import TrustAdapterScore, TrustComponentScore, TrustDomainScore
@@ -116,11 +116,169 @@ def apply_local_trust_metadata(
         )
     )
 
+    local_security = _local_skill_security_for_artifact(
+        artifact,
+        item_kind=item_kind,
+        metadata=metadata,
+        captured_at=captured_at,
+        cisco_runs=cisco_runs,
+        workspace_dir=workspace_dir,
+    )
+    if local_security is not None:
+        enriched["localSecurity"] = local_security
+
     if trust_layers:
         enriched["trustLayers"] = _merge_trust_layers(metadata.get("trustLayers"), trust_layers)
     return enriched
 
 
+def _local_skill_security_for_artifact(
+    artifact: object,
+    *,
+    item_kind: InventoryItemKind,
+    metadata: dict[str, object],
+    captured_at: str,
+    cisco_runs: tuple[object, ...],
+    workspace_dir: Path | None,
+) -> dict[str, object] | None:
+    from .inventory_contract import _normalize_inventory_datetime
+
+    if item_kind != "skill" or metadata.get("artifactType") != "skill":
+        return None
+
+    trust_root = _trust_root_for_artifact(artifact, item_kind=item_kind, workspace_dir=workspace_dir)
+    if trust_root is None:
+        return None
+
+    run = next(
+        (
+            candidate
+            for candidate in cisco_runs
+            if getattr(candidate, "source", None) == "cisco-skill-scanner"
+            and _matches_skill_cisco_run(
+                artifact,
+                item_kind=item_kind,
+                run=candidate,
+                workspace_dir=workspace_dir,
+            )
+        ),
+        None,
+    )
+    if run is None:
+        return None
+
+    status = str(getattr(run, "status", "unknown"))
+    normalized_captured_at = _normalize_inventory_datetime(captured_at)
+    findings = _local_skill_security_findings(run, skill_root=trust_root)
+    severity_counts = _cisco_severity_counts(run)
+    score = _cisco_layer_score(severity_counts) if status == "enabled" else None
+    safety = None
+    if score is not None:
+        safety = {
+            "score": score,
+            "label": _local_skill_security_label(score),
+            "findingsTotal": len(findings),
+            "highFindings": sum(1 for finding in findings if finding["severity"] == "high"),
+            "scriptsTotal": _local_skill_scripts_total(run),
+            "permissionsMissing": [],
+        }
+
+    run_metadata = getattr(run, "metadata", None)
+    metadata_payload: dict[str, object] = {
+        "scannerSource": str(getattr(run, "source", "unknown")),
+        "message": str(getattr(run, "message", "")),
+        "findingsBySeverity": severity_counts,
+        "totalFindings": len(findings),
+    }
+    duration_ms = getattr(run, "duration_ms", None)
+    if isinstance(duration_ms, int):
+        metadata_payload["durationMs"] = duration_ms
+    if isinstance(run_metadata, dict):
+        for key in ("analyzersUsed", "policyName", "mode", "skillsScanned", "skillsSkipped"):
+            value = run_metadata.get(key)
+            if value is not None:
+                metadata_payload[key] = value
+
+    return {
+        "entityType": "skill",
+        "source": "local_indexed",
+        "provider": "cisco-skill-scanner",
+        "status": status,
+        "capturedAt": normalized_captured_at,
+        "safety": safety,
+        "findings": findings,
+        "metadata": metadata_payload,
+    }
+
+
+def _local_skill_security_findings(
+    run: object,
+    *,
+    skill_root: Path,
+) -> list[dict[str, object]]:
+    results: list[dict[str, object]] = []
+    for finding in tuple(getattr(run, "findings", ()) or ()):
+        file_path = getattr(finding, "file_path", None)
+        if isinstance(file_path, str) and file_path.strip():
+            path = Path(file_path)
+            if not _paths_related(skill_root, path):
+                continue
+            try:
+                relative_file = str(path.resolve().relative_to(skill_root.resolve()))
+            except ValueError:
+                relative_file = path.name
+        else:
+            relative_file = "SKILL.md"
+
+        results.append(
+            {
+                "ruleId": str(getattr(finding, "rule_id", "unknown")),
+                "severity": _local_skill_security_severity(getattr(finding, "severity", None)),
+                "file": relative_file,
+                "message": _local_skill_security_message(finding),
+            }
+        )
+    return results
+
+
+def _local_skill_security_severity(value: object) -> str:
+    severity = value.value if isinstance(value, Severity) else str(value).lower()
+    if severity in {"critical", "high"}:
+        return "high"
+    if severity == "medium":
+        return "medium"
+    return "low"
+
+
+def _local_skill_security_message(finding: object) -> str:
+    description = getattr(finding, "description", None)
+    if isinstance(description, str) and description.strip():
+        return description.strip()
+    title = getattr(finding, "title", None)
+    if isinstance(title, str) and title.strip():
+        return title.strip()
+    return "Skill security finding"
+
+
+def _local_skill_security_label(score: int) -> str:
+    if score >= 90:
+        return "safe"
+    if score >= 70:
+        return "review"
+    if score >= 45:
+        return "caution"
+    return "unsafe"
+
+
+def _local_skill_scripts_total(run: object) -> int:
+    metadata = getattr(run, "metadata", None)
+    if isinstance(metadata, dict):
+        value = metadata.get("skillsScanned")
+        if isinstance(value, int):
+            return max(0, value)
+    return 0
+
+
 def _local_trust_domain_for_artifact(
     artifact: object,
     *,

{plugin_scanner-2.0.666 → plugin_scanner-2.0.668}/src/codex_plugin_scanner/guard/cli/commands_dispatch_admin.py

@@ -25,6 +25,8 @@ def _run_guard_exceptions_command(
     items = [
         item for item in active_items if isinstance(item.get("expires_at"), str) and str(item["expires_at"]).strip()
     ]
+    cloud_items = store.list_cloud_exceptions(getattr(args, "harness", None))
+    items = cloud_items + items
     _emit("exceptions", {"generated_at": _now(), "items": items}, getattr(args, "json", False))
     return 0
 

plugin_scanner-2.0.668/src/codex_plugin_scanner/guard/cloud_exceptions.py

@@ -0,0 +1,299 @@
+"""Cloud exception DTO parsing and storage helpers (HGLP046-HGLP060)."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from datetime import datetime, timezone
+
+from .models import CloudException
+
+_CLOUD_EXCEPTION_SCOPES = frozenset({"artifact", "publisher", "harness", "workspace", "global"})
+_CLOUD_EXCEPTION_EFFECTS = frozenset({"allow"})
+_CLOUD_EXCEPTION_ACK_STATUSES = frozenset({"pending", "synced", "failed", "offline"})
+
+
+def _non_empty_string(value: object) -> str | None:
+    return value if isinstance(value, str) and value.strip() else None
+
+
+def _parse_iso_timestamp(value: object) -> datetime | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+    normalized = value.replace("Z", "+00:00")
+    try:
+        parsed = datetime.fromisoformat(normalized)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed
+
+
+def _normalized_timestamp_string(value: object) -> str | None:
+    parsed = _parse_iso_timestamp(value)
+    if parsed is None:
+        return None
+    return parsed.astimezone(timezone.utc).isoformat()
+
+
+def _cloud_exception_is_active(item: CloudException, *, now: str | None = None) -> bool:
+    expiry = _parse_iso_timestamp(item.expiry)
+    if expiry is None:
+        return False
+    current = _parse_iso_timestamp(now or datetime.now(timezone.utc).isoformat())
+    if current is None:
+        return False
+    return expiry > current
+
+
+def _policy_bundle_cloud_exception_is_valid(item: object) -> bool:
+    if not isinstance(item, dict):
+        return False
+    exception_id = _non_empty_string(item.get("exceptionId") or item.get("id"))
+    if exception_id is None:
+        return False
+    effect = item.get("effect") or "allow"
+    if effect not in _CLOUD_EXCEPTION_EFFECTS:
+        return False
+    scope = item.get("scope")
+    if scope not in _CLOUD_EXCEPTION_SCOPES:
+        return False
+    if _non_empty_string(item.get("owner")) is None:
+        return False
+    if _normalized_timestamp_string(item.get("expiresAt") or item.get("expiry")) is None:
+        return False
+    harness = item.get("harness")
+    if scope == "harness":
+        if not isinstance(harness, str) or not harness.strip():
+            return False
+    elif harness is not None and not isinstance(harness, str):
+        return False
+    approver = item.get("approver")
+    if approver is not None and _non_empty_string(approver) is None:
+        return False
+    source_receipt_id = item.get("sourceReceiptId")
+    return source_receipt_id is None or _non_empty_string(source_receipt_id) is not None
+
+
+def policy_bundle_cloud_exceptions_are_valid(policy_bundle: dict[str, object]) -> bool:
+    cloud_exceptions = policy_bundle.get("cloudExceptions")
+    if cloud_exceptions is None:
+        return True
+    if not isinstance(cloud_exceptions, list):
+        return False
+    return all(_policy_bundle_cloud_exception_is_valid(item) for item in cloud_exceptions)
+
+
+def _resolve_cloud_exception_ack_status(
+    *,
+    device_id: str | None,
+    policy_bundle: dict[str, object] | None,
+    policy_bundle_ack: dict[str, object] | None,
+) -> str | None:
+    if isinstance(policy_bundle_ack, dict):
+        ack_status = policy_bundle_ack.get("status")
+        if isinstance(ack_status, str) and ack_status in _CLOUD_EXCEPTION_ACK_STATUSES:
+            return ack_status
+    if not isinstance(policy_bundle, dict):
+        return None
+    acknowledgements = policy_bundle.get("acknowledgements")
+    if not isinstance(acknowledgements, list) or device_id is None:
+        return None
+    for acknowledgement in acknowledgements:
+        if not isinstance(acknowledgement, dict):
+            continue
+        if str(acknowledgement.get("deviceId")) != device_id:
+            continue
+        status = acknowledgement.get("status")
+        if isinstance(status, str) and status in _CLOUD_EXCEPTION_ACK_STATUSES:
+            return status
+    return None
+
+
+def cloud_exception_from_mapping(
+    item: dict[str, object],
+    *,
+    bundle_hash: str | None = None,
+    ack_status: str | None = None,
+    rejection_reason: str | None = None,
+    provenance: str = "receipt-sync",
+) -> CloudException | None:
+    exception_id = _non_empty_string(item.get("exceptionId") or item.get("id"))
+    if exception_id is None:
+        return None
+    scope = item.get("scope")
+    if scope not in _CLOUD_EXCEPTION_SCOPES:
+        return None
+    effect = item.get("effect") or "allow"
+    if effect not in _CLOUD_EXCEPTION_EFFECTS:
+        return None
+    owner = _non_empty_string(item.get("owner"))
+    expiry = _normalized_timestamp_string(item.get("expiresAt") or item.get("expiry"))
+    if owner is None or expiry is None:
+        return None
+    harness_value = item.get("harness")
+    harness = harness_value if isinstance(harness_value, str) and harness_value.strip() else None
+    if scope == "harness" and harness is None:
+        return None
+    approver = _non_empty_string(item.get("approver"))
+    source_receipt_id = _non_empty_string(item.get("sourceReceiptId") or item.get("source_receipt_id"))
+    last_used_at = _normalized_timestamp_string(item.get("lastUsedAt") or item.get("last_used_at"))
+    resolved_ack = ack_status or _non_empty_string(item.get("ackStatus") or item.get("ack_status"))
+    if resolved_ack is not None and resolved_ack not in _CLOUD_EXCEPTION_ACK_STATUSES:
+        resolved_ack = None
+    resolved_bundle_hash = _non_empty_string(item.get("bundleHash") or item.get("bundle_hash")) or bundle_hash
+    return CloudException(
+        id=exception_id,
+        effect=effect,  # type: ignore[arg-type]
+        scope=scope,  # type: ignore[arg-type]
+        harness=harness,
+        owner=owner,
+        approver=approver,
+        expiry=expiry,
+        source_receipt_id=source_receipt_id,
+        bundle_hash=resolved_bundle_hash,
+        ack_status=resolved_ack,  # type: ignore[arg-type]
+        last_used_at=last_used_at,
+        rejection_reason=_non_empty_string(item.get("rejectionReason") or item.get("rejection_reason"))
+        or rejection_reason,
+        provenance=provenance if provenance in {"receipt-sync", "policy-bundle"} else "receipt-sync",  # type: ignore[arg-type]
+    )
+
+
+def build_cloud_exceptions_from_policy_bundle(
+    policy_bundle: dict[str, object],
+    *,
+    device_id: str | None = None,
+    policy_bundle_ack: dict[str, object] | None = None,
+) -> list[CloudException]:
+    cloud_exceptions = policy_bundle.get("cloudExceptions")
+    if not isinstance(cloud_exceptions, list):
+        return []
+    bundle_hash = _non_empty_string(policy_bundle.get("bundleHash"))
+    ack_status = _resolve_cloud_exception_ack_status(
+        device_id=device_id,
+        policy_bundle=policy_bundle,
+        policy_bundle_ack=policy_bundle_ack,
+    )
+    items: list[CloudException] = []
+    for raw_item in cloud_exceptions:
+        if not isinstance(raw_item, dict):
+            continue
+        parsed = cloud_exception_from_mapping(
+            raw_item,
+            bundle_hash=bundle_hash,
+            ack_status=ack_status,
+            provenance="policy-bundle",
+        )
+        if parsed is not None:
+            items.append(parsed)
+    return items
+
+
+def cloud_exception_from_stored_dict(item: dict[str, object]) -> CloudException | None:
+    exception_id = _non_empty_string(item.get("id"))
+    if exception_id is None:
+        return None
+    scope = item.get("scope")
+    if scope not in _CLOUD_EXCEPTION_SCOPES:
+        return None
+    effect = item.get("effect") or "allow"
+    if effect not in _CLOUD_EXCEPTION_EFFECTS:
+        return None
+    owner = _non_empty_string(item.get("owner"))
+    expiry = _normalized_timestamp_string(item.get("expiry"))
+    if owner is None or expiry is None:
+        return None
+    harness_value = item.get("harness")
+    harness = harness_value if isinstance(harness_value, str) and harness_value.strip() else None
+    if scope == "harness" and harness is None:
+        return None
+    ack_status = item.get("ack_status")
+    if ack_status is not None and ack_status not in _CLOUD_EXCEPTION_ACK_STATUSES:
+        ack_status = None
+    resolved_provenance = item.get("provenance")
+    if resolved_provenance not in {"receipt-sync", "policy-bundle"}:
+        resolved_provenance = "receipt-sync"
+    return CloudException(
+        id=exception_id,
+        effect=effect,  # type: ignore[arg-type]
+        scope=scope,  # type: ignore[arg-type]
+        harness=harness,
+        owner=owner,
+        approver=_non_empty_string(item.get("approver")),
+        expiry=expiry,
+        source_receipt_id=_non_empty_string(item.get("source_receipt_id")),
+        bundle_hash=_non_empty_string(item.get("bundle_hash")),
+        ack_status=ack_status,  # type: ignore[arg-type]
+        last_used_at=_normalized_timestamp_string(item.get("last_used_at")),
+        rejection_reason=_non_empty_string(item.get("rejection_reason")),
+        provenance=resolved_provenance,  # type: ignore[arg-type]
+    )
+
+
+def _stored_cloud_exception_provenance(item: dict[str, object]) -> str:
+    provenance = item.get("provenance")
+    if provenance in {"receipt-sync", "policy-bundle"}:
+        return str(provenance)
+    if _non_empty_string(item.get("bundle_hash")) is not None:
+        return "policy-bundle"
+    return "receipt-sync"
+
+
+def stored_receipt_sync_cloud_exceptions(items: list[dict[str, object]]) -> list[CloudException]:
+    preserved = [
+        item
+        for item in items
+        if isinstance(item, dict) and _stored_cloud_exception_provenance(item) == "receipt-sync"
+    ]
+    return build_cloud_exceptions_from_stored_items(preserved)
+
+
+def build_cloud_exceptions_from_stored_items(items: list[dict[str, object]]) -> list[CloudException]:
+    parsed: list[CloudException] = []
+    for raw_item in items:
+        item = cloud_exception_from_stored_dict(raw_item)
+        if item is not None:
+            parsed.append(item)
+    return parsed
+
+
+def build_cloud_exceptions_from_sync_payload(
+    exceptions: list[dict[str, object]],
+    *,
+    bundle_hash: str | None = None,
+    ack_status: str | None = None,
+) -> list[CloudException]:
+    items: list[CloudException] = []
+    for raw_item in exceptions:
+        parsed = cloud_exception_from_mapping(
+            raw_item,
+            bundle_hash=bundle_hash,
+            ack_status=ack_status,
+        )
+        if parsed is not None:
+            items.append(parsed)
+    return items
+
+
+def dedupe_cloud_exceptions(items: list[CloudException]) -> list[CloudException]:
+    deduped: dict[str, CloudException] = {}
+    for item in items:
+        deduped[item.id] = item
+    return list(deduped.values())
+
+
+def list_active_cloud_exceptions(
+    items: list[CloudException],
+    *,
+    harness: str | None = None,
+    now: str | None = None,
+) -> list[CloudException]:
+    active = [item for item in items if _cloud_exception_is_active(item, now=now)]
+    if harness is None:
+        return active
+    return [item for item in active if item.harness in {harness, "*"}]
+
+
+def cloud_exception_to_dict(item: CloudException) -> dict[str, object]:
+    return asdict(item)