Drop ignored omit_license_details param from cached diff-scan polls

The API ignores omit_license_details when cached=true - cached diff-scan
results always embed license details - so sending the param suggested a
lean-response guarantee the polling path doesn't have. Document the
caveat instead: if the heavier payload ever gets truncated on a huge
dependency tree, JSON parsing fails and the caller already falls back
to the legacy streaming comparison, which still requests the lean
payload. include_license_details now only governs that fallback call.

Flagged by Cursor Bugbot on #284.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: lelia

socketsecurity/core/__init__.py

@@ -1325,8 +1325,7 @@ def get_license_text_via_purl(self, packages: dict[str, Package], batch_size: in
     def get_diff_scan_artifacts(
             self,
             head_full_scan_id: str,
-            new_full_scan_id: str,
-            include_license_details: bool = False
+            new_full_scan_id: str
     ) -> DiffArtifacts:
         """Compare two full scans via the diff-scans endpoints, polling for the result.
 
@@ -1341,12 +1340,14 @@ def get_diff_scan_artifacts(
         and ``full-scans:list`` scopes; callers are expected to catch failures and
         fall back to the legacy streaming comparison.
 
+        Note that cached diff-scan responses always embed per-package license
+        details (the API ignores ``omit_license_details`` when ``cached=true``),
+        so unlike the legacy streaming comparison there is no lean-response
+        option here; see the comment on ``poll_params`` below.
+
         Args:
             head_full_scan_id: The before/base full scan ID
             new_full_scan_id: The after/head full scan ID
-            include_license_details: Whether to keep embedded per-package license
-                details in the response (see get_added_and_removed_packages for
-                why this defaults to False)
 
         Returns:
             DiffArtifacts with the added/removed/unchanged/replaced/updated lists
@@ -1368,10 +1369,15 @@ def get_diff_scan_artifacts(
         # which case the create response already carries the artifacts.
         artifacts_dict = diff_scan.get("artifacts")
 
-        poll_params = {
-            "cached": "true",
-            "omit_license_details": "false" if include_license_details else "true",
-        }
+        # cached=true is the polling contract (202 while computing, 200 when
+        # ready). The API ignores omit_license_details when cached=true - cached
+        # results always embed license details - so there is no lean-response
+        # option on this path (unlike stream_diff with
+        # include_license_details=false, the CE-224 mitigation). If that extra
+        # payload ever gets a response truncated on a huge dependency tree,
+        # response.json() fails and the caller falls back to the legacy
+        # streaming comparison, which still requests the lean payload.
+        poll_params = {"cached": "true"}
         deadline = time.monotonic() + DIFF_SCAN_POLL_TIMEOUT_SECONDS
         interval = DIFF_SCAN_POLL_INITIAL_INTERVAL_SECONDS
         while artifacts_dict is None:
@@ -1421,8 +1427,12 @@ def get_added_and_removed_packages(
         Args:
             head_full_scan_id: Previous scan (maybe None if first scan)
             new_full_scan_id: New scan just created
-            include_license_details: Whether to ask the diff endpoint to embed
-                per-package license attribution/details in the response.
+            include_license_details: Whether to ask the *legacy streaming* diff
+                endpoint to embed per-package license attribution/details in the
+                response. Only consulted on the fallback path: the primary
+                diff-scans path always receives embedded license details, since
+                the API ignores ``omit_license_details`` for cached reads (see
+                get_diff_scan_artifacts).
 
                 Defaults to ``False`` on purpose. The diff endpoint exists to
                 compare alerts between two scans; the license fields it can embed
@@ -1453,8 +1463,7 @@ def get_added_and_removed_packages(
         try:
             diff_artifacts = self.get_diff_scan_artifacts(
                 head_full_scan_id,
-                new_full_scan_id,
-                include_license_details=include_license_details
+                new_full_scan_id
             )
         except Exception as error:
             # SDK error messages can span many lines (path + response headers); the

tests/core/test_sdk_methods.py

@@ -236,14 +236,14 @@ def test_get_added_and_removed_packages(core):
     assert create_params["after"] == "new"
     assert create_params["on_duplicate"] == "redirect"
 
-    # include_license_details defaults to False: the diff path never consumes
-    # embedded license data (license artifacts come from the PURL endpoint), so
-    # requesting it only bloats the response and risks the truncation
-    # crash on large repos.
+    # cached=true is the polling contract (202 while computing, 200 when ready).
+    # No omit_license_details param: the API ignores it for cached reads (cached
+    # results always embed license details), so sending it would only suggest a
+    # leanness guarantee this path doesn't have.
     core.sdk.diffscans.get.assert_called_once_with(
         core.config.org_slug,
         "diff-scan-123",
-        params={"cached": "true", "omit_license_details": "true"},
+        params={"cached": "true"},
     )
     core.sdk.fullscans.stream_diff.assert_not_called()
 
@@ -260,13 +260,21 @@ def test_get_added_and_removed_packages(core):
     assert "pypi/direct_package_1@1.6.0" in all_packages  # Unchanged package is in full package map
 
 def test_get_added_and_removed_packages_license_override(core):
-    """The include_license_details override seam still works when explicitly requested."""
+    """include_license_details only governs the legacy fallback path now: the
+    diff-scans path always receives embedded license details (the API ignores
+    omit_license_details for cached reads), so the seam must survive through to
+    the stream_diff call when the primary path is unavailable."""
+    from socketdev.exceptions import APIFailure
+
+    core.sdk.diffscans.create_from_ids.side_effect = APIFailure("forbidden", status_code=403)
     core.get_added_and_removed_packages("head", "new", include_license_details=True)
 
-    core.sdk.diffscans.get.assert_called_once_with(
+    core.sdk.fullscans.stream_diff.assert_called_once_with(
         core.config.org_slug,
-        "diff-scan-123",
-        params={"cached": "true", "omit_license_details": "false"},
+        "head",
+        "new",
+        use_types=True,
+        include_license_details="true",
     )
 
 def test_empty_alerts_preserved(core):