fix(zipf): reject KS misfits and alpha pinned at ALPHA_LO

[daedalus]

Bug

On png_read_noasan.so built against vendored, instrumented libpng (30k execs, 139 seeds, 1501 edges), the seeds-per-edge spectrum is not a power law. The number of edges falls from 188 owned by 1 seed to about 20 owned by 12 seeds, then 95 edges are owned by 137 of the 139 seeds (the parse path every input takes). fit_zipf returned alpha=1.01 (the lower search bound), KS=0.169, and still classified it POWER_LAW. The 95% KS critical value at n = 1501 is 0.035.

Cause: _classify only checked two things, the Vuong test against a geometric and α pinned at ALPHA_HI. A spectrum that is neither a power law nor geometric still wins the Vuong test. The effect: the saturation-gate veto from #22 fired on a signal that doesn't hold.

Fix

_classify now also returns NOT_POWER_LAW when:

• KS > KS_95 / sqrt(n_tail), with KS_95 = 1.36 (Kolmogorov 95%). Two things make this threshold err toward accepting: the parameters are fitted, and xmin is chosen as the lowest-KS candidate.
• α is pinned at either end of the search range, not only ALPHA_HI.

The real png spectrum now reads not_power_law.

A second commit comes from Copilot's review overview. The summary, report and stats file printed s = 1/(α−1) for rejected fits (s=99.96 on png). They now show α and the verdict, and include s only for accepted power-law fits.

Tests

• test_regression_zipf_ks_misfit_rejected: png-shaped fixture (decaying head plus hot core); α is inside the range but the fit is bad.
• test_regression_zipf_alpha_pinned_low_rejected: a capped law with true α = 0.6.
• test_true_power_law_passes_ks_guard: falsification check. The exact fixtures sit 3–50× under the critical value.
• TestRegressionZipfExponentOnMisfit: checks that the summary, report and stats file leave out s for rejected fits, and keep it for accepted ones (falsification).
• Every regression test failed before its fix and passes after it. 201 tests across the zipf, gate, report and stats suites pass. ruff, strict mypy, lizard and all pre-commit hooks (including impactguard) pass.

Also

docs/TODO.md: new item. build_targets.sh --vendor-tracecmp can't configure vendored libpng, because the coverage flags in CFLAGS break configure's link test. I worked around it by hand for this measurement.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UbKUguEPpHswuuUbhCXSuT

Summary by Sourcery

Strengthen Zipf fit validation and report rejected fits without presenting invalid exponents.

Bug Fixes:

• Reject Zipf fits with statistically significant KS misfits or alpha estimates pinned at either search-boundary, preventing non-power-law spectra from being classified as power laws.
• Stop reporting the derived rank-frequency exponent for rejected Zipf fits while retaining it for accepted power-law fits.

Enhancements:

• Document the additional Zipf classification guards and update the saturation-gate analysis notes.

Documentation:

• Document the vendored libpng trace-comparison configuration issue and the updated Zipf classification criteria.

Tests:

• Add regression coverage for KS misfits, low-bound alpha pinning, valid power laws, and exponent reporting across summaries, reports, and stats.

[sourcery-ai]

Reviewer's Guide

The PR hardens Zipf-tail classification by requiring an acceptable absolute KS fit and an interior alpha estimate, preventing non-power-law hot-core spectra and low-alpha boundary fits from triggering the saturation-gate veto while preserving valid power-law detection.

Flow diagram for hardened Zipf tail classification

flowchart TD
    A["Fit Zipf tail"] --> B["_classify(alpha, xmin, n_tail, total, ks, vuong)"]
    B --> C{"Alpha pinned at either bound?"}
    C -->|Yes| N["NOT_POWER_LAW"]
    C -->|No| D{"KS > 1.36 / sqrt(n_tail)?"}
    D -->|Yes| N
    D -->|No| E{"Tail fraction < 20%?"}
    E -->|Yes| N
    E -->|No| F{"Vuong < 1.96?"}
    F -->|Yes| N
    F -->|No| P["POWER_LAW"]
    P --> G["Saturation-gate veto may engage"]
    N --> H["Saturation-gate veto blocked"]

Loading

File-Level Changes

Change	Details	Files
Added absolute goodness-of-fit and parameter-bound checks to reject invalid Zipf classifications.	Introduced a sample-size-aware KS critical-value guard using 1.36/√n_tail. Treats alpha pinned at either ALPHA_LO or ALPHA_HI as NOT_POWER_LAW. Retains Vuong, tail-fraction, and existing classification checks while documenting why Vuong alone is insufficient.	src/fuzzer_tool/core/zipf.py
Added regression and falsification coverage for Zipf misclassification cases.	Added a png-shaped hot-core fixture whose interior-alpha but poor-KS fit is rejected. Added coverage for a low-alpha capped distribution pinned at ALPHA_LO. Verified representative exact power laws remain accepted by the KS guard.	tests/test_zipf.py
Updated documentation to describe the new Zipf safeguards and record a vendored-libpng build limitation.	Documented KS misfit and two-sided pinned-alpha guards in the Zipf overview. Added a TODO for configure failures caused by sanitizer coverage flags and instrumented zlib/libpng probes.	docs/DEEP_DIVE.md docs/TODO.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Sorry @daedalus, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 5 days and 14 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Misleading s output and unaccounted xmin selection can undermine the new classification guard.

Review effort: Lite
Findings: None

What changed in this PR

Strengthens Zipf-tail classification by rejecting poor KS fits and alpha estimates at search boundaries.

Changes:

• Adds KS misfit and boundary-alpha guards.
• Adds regression and falsification tests.
• Documents Zipf behavior and the libpng configuration limitation.

File	Summary
tests/​test_zipf.py	Adds Zipf regression and validity tests.
src/​fuzzer_tool/​core/​zipf.py	Adds classification safeguards.
docs/​TODO.md	Records the libpng build limitation.
docs/​DEEP_DIVE.md	Documents updated Zipf safeguards.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.