perf(diff): skip unchanged artifacts when no output reads them

Cached diff-scan responses embed every unchanged artifact at roughly 1 KB each. On a large dependency tree that is nearly the whole response — measured at ~11 MB for a tree with ~10k unchanged packages — downloaded, deserialised into Package objects and then discarded on every pull request. omit_unchanged is honored by the API (unlike omit_license_details, which cached responses ignore), so request it whenever no enabled output reads that half of the comparison. Verified against the live API through the SDK: 192 artifacts -> 57. Every consumer is behind an opt-in flag, so the gate is centralised in Core._requires_unchanged_artifacts with the reasoning recorded there: - --strict-blocking blocks on pre-existing issues via diff.unchanged_alerts - --enable-gitlab-security includes them in the dependency scanning report - --generate-license enumerates diff.packages, which must list every dependency - --legal-format fossa reports all currently-present issues Diff.to_dict serialises them too but has no callers. When cli_config is absent the caller is unknown, so the full payload is kept. Tests parametrise over every flag in that list so a new reader of diff.unchanged_alerts or diff.packages cannot be added without also updating the gate. The completion log reports omit_unchanged so it is visible whether the optimisation engaged on a given run. Ref: Product Launch Plan Outline

Books And Reading

@@ -22,6 +22,16 @@
  smaller local fallback pattern set. Manifest results from `--sub-path` routing
  are reused during scan creation.
 
+### Changed: scan comparisons no longer fetch unused artifacts
+
+- Scan comparisons now ask the API to omit unchanged artifacts unless an enabled
+ output actually reads them (`--strict-blocking`, `--enable-gitlab-security`,
+ `--generate-license`, or `--legal-format fossa`). Cached comparison responses
+ embed every unchanged artifact at roughly 1 KB each, so on a large dependency
+ tree this was most of the response — over 10 MB for a tree of ~10k unchanged
+ packages — downloaded and parsed on every pull request even when nothing read
+ it. Behavior is unchanged for any run that uses those outputs.
+
 ### Changed: scan comparison timing is easier to attribute
 
 - Lowered the diff-scan poll ceiling from 30s to 10s. A finished comparison is no

Letter Of Intent For Mall Display

@@ -1608,14 +1608,13 @@ def get_diff_scan_artifacts(
  #
  # Verified against the live API: passing omit_license_details alongside
  # cached=true leaves the license fields in the response, but omit_unchanged
- # IS honored and drops the unchanged artifacts entirely (~1.1 KB each). Not
- # sent here because unchanged artifacts are not only used by
- # --strict-blocking: create_security_comment_gitlab and the FOSSA compat
- # issue list both read diff.unchanged_alerts unconditionally, so omitting
- # them would silently shrink those outputs. Gating it correctly across all
- # three consumers is worth doing - on a tree with ~10k unchanged artifacts
- # it is over 10 MB of response - but it needs its own change.
+ # IS honored and drops the unchanged artifacts entirely (~1.1 KB each), so
+ # it is requested whenever no enabled output reads them. See
+ # _requires_unchanged_artifacts.
  poll_params = {"cached": "true"}
+ omit_unchanged = not self._requires_unchanged_artifacts()
+ if omit_unchanged:
+ poll_params["omit_unchanged"] = "true"
  poll_start = time.monotonic()
  deadline = poll_start + DIFF_SCAN_POLL_TIMEOUT_SECONDS
  interval = DIFF_SCAN_POLL_INITIAL_INTERVAL_SECONDS
@@ -1648,7 +1647,8 @@ def get_diff_scan_artifacts(
  log.info(
  "Diff scan comparison ready in "
  f"{time.monotonic() - poll_start:.2f}s: id={diff_scan_id}, "
- f"polls={polls}, wait_before_final_poll={last_interval:.0f}s"
+ f"polls={polls}, wait_before_final_poll={last_interval:.0f}s, "
+ f"omit_unchanged={str(omit_unchanged).lower()}"
  )
  break
  if time.monotonic() >= deadline:
@@ -1666,6 +1666,39 @@ def get_diff_scan_artifacts(
  for key in ("added", "removed", "unchanged", "replaced", "updated")
  })
 
+ def _requires_unchanged_artifacts(self) -> bool:
+ """Whether any enabled output reads the unchanged half of a comparison.
+
+ A cached diff-scan response embeds every unchanged artifact at roughly 1 KB
+ each, so on a large dependency tree they are almost the entire payload
+ (~11 MB for a tree of ~10k unchanged packages) even though most runs never
+ look at them. Every consumer is behind an opt-in flag:
+
+ - ``--strict-blocking`` reads ``diff.unchanged_alerts`` to block on
+ pre-existing issues (socketcli, output, alert_selection, slack plugin).
+ - ``--enable-gitlab-security`` includes them in the GitLab dependency
+ scanning report (Messages.create_security_comment_gitlab).
+ - ``--generate-license`` enumerates ``diff.packages``, which must list every
+ dependency, not just the changed ones.
+ - ``--legal-format fossa`` reports all currently-present issues, matching
+ FOSSA's point-in-time snapshot semantics.
+
+ ``Diff.to_dict`` also serializes them but has no callers. When cli_config is
+ absent the caller is unknown, so the full payload is kept.
+
+ Keep this in sync with those consumers; test_unchanged_artifacts_gating
+ pins the list.
+ """
+ config = self.cli_config
+ if config is None:
+ return True
+ return bool(
+ getattr(config, "strict_blocking", False)
+ or getattr(config, "enable_gitlab_security", False)
+ or getattr(config, "generate_license", False)
+ or getattr(config, "legal_format", "socket") == "fossa"
+ )
+
  def get_added_and_removed_packages(
  self,
  head_full_scan_id: str,

Budget Outline For Product Development

@@ -153,3 +153,65 @@ def test_max_poll_interval_bounds_dead_time_for_ci_budgets():
  core_module.DIFF_SCAN_POLL_INITIAL_INTERVAL_SECONDS
  <= core_module.DIFF_SCAN_POLL_MAX_INTERVAL_SECONDS
  )
+
+
+UNCHANGED_ARTIFACT_CONSUMERS = [
+ # flag name, value that makes the flag active
+ ("strict_blocking", True),
+ ("enable_gitlab_security", True),
+ ("generate_license", True),
+ ("legal_format", "fossa"),
+]
+
+
+@pytest.mark.parametrize(("flag", "value"), UNCHANGED_ARTIFACT_CONSUMERS)
+def test_unchanged_artifacts_gating(core, diff_scan_get_response, flag, value):
+ """Any output that reads unchanged artifacts must keep them in the response.
+
+ This pins the consumer list in Core._requires_unchanged_artifacts: adding a new
+ reader of diff.unchanged_alerts or diff.packages without adding it here (and to
+ that method) would silently ship an empty result to that output.
+ """
+ from types import SimpleNamespace
+
+ defaults = {name: (False if name != "legal_format" else "socket")
+ for name, _ in UNCHANGED_ARTIFACT_CONSUMERS}
+ core.cli_config = SimpleNamespace(**{**defaults, flag: value})
+ core.sdk.diffscans.get.side_effect = None
+ core.sdk.diffscans.get.return_value = diff_scan_get_response
+
+ core.get_diff_scan_artifacts("head", "new")
+
+ params = core.sdk.diffscans.get.call_args.kwargs["params"]
+ assert "omit_unchanged" not in params, f"{flag}={value} still needs unchanged artifacts"
+
+
+def test_unchanged_artifacts_omitted_when_no_output_reads_them(core, diff_scan_get_response):
+ """With no such flag set, the ~1 KB-per-artifact unchanged half is not fetched."""
+ from types import SimpleNamespace
+
+ core.cli_config = SimpleNamespace(
+ strict_blocking=False,
+ enable_gitlab_security=False,
+ generate_license=False,
+ legal_format="socket",
+ )
+ core.sdk.diffscans.get.side_effect = None
+ core.sdk.diffscans.get.return_value = diff_scan_get_response
+
+ core.get_diff_scan_artifacts("head", "new")
+
+ params = core.sdk.diffscans.get.call_args.kwargs["params"]
+ assert params["cached"] == "true"
+ assert params["omit_unchanged"] == "true"
+
+
+def test_unknown_caller_keeps_full_payload(core, diff_scan_get_response):
+ """cli_config is optional; without it, do not assume unchanged is unused."""
+ core.cli_config = None
+ core.sdk.diffscans.get.side_effect = None
+ core.sdk.diffscans.get.return_value = diff_scan_get_response
+
+ core.get_diff_scan_artifacts("head", "new")
+
+ assert "omit_unchanged" not in core.sdk.diffscans.get.call_args.kwargs["params"]